mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +00:00
johndoe6345789
b3e17e7dd4
- Created a new troubleshooting guide in README.md for common issues and testing problems. - Updated package.json to include new act commands for linting, type checking, building, and diagnosing workflows. - Added a pre-commit hook script to validate workflows before commits. - Enhanced run-act.sh script with logging, Docker checks, and improved output formatting. - Improved test-workflows.sh with an interactive menu and performance tracking. - Introduced setup-act.sh for quick setup and testing of act integration.
235 lines
8.5 KiB
Markdown
235 lines
8.5 KiB
Markdown
# 📚 Complete Index: Size Limits & Refactoring
|
|
|
|
## 🎯 Start Here
|
|
|
|
**New to this?** Start with one of these:
|
|
1. **5 minute intro**: [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md)
|
|
2. **Visual guide**: [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md)
|
|
3. **Full summary**: [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md)
|
|
|
|
## 📋 Essential Files
|
|
|
|
### Tools & Automation
|
|
| File | Purpose | Who Uses |
|
|
|------|---------|----------|
|
|
| [scripts/enforce-size-limits.ts](scripts/enforce-size-limits.ts) | Size limit checker tool | All developers |
|
|
| [.github/workflows/size-limits.yml](.github/workflows/size-limits.yml) | GitHub Actions CI/CD | Automation |
|
|
| [.git/hooks/pre-commit](.git/hooks/pre-commit) | Local pre-commit check | Git hooks |
|
|
|
|
### Code: Hooks
|
|
| File | Purpose | Size | Example |
|
|
|------|---------|------|---------|
|
|
| [src/hooks/useGitHubFetcher.ts](src/hooks/useGitHubFetcher.ts) | GitHub API integration | 65 LOC | API calls, auth |
|
|
| [src/hooks/useAutoRefresh.ts](src/hooks/useAutoRefresh.ts) | Auto-refresh polling | 48 LOC | Timers, intervals |
|
|
| [src/hooks/useFileTree.ts](src/hooks/useFileTree.ts) | File tree operations | 85 LOC | Tree traversal, CRUD |
|
|
| [src/hooks/useCodeEditor.ts](src/hooks/useCodeEditor.ts) | Editor state | 68 LOC | Tabs, dirty state |
|
|
| [src/hooks/index.ts](src/hooks/index.ts) | Barrel export | 20 LOC | Import point |
|
|
|
|
### Code: Components
|
|
| File | Size | Note |
|
|
|------|------|------|
|
|
| [src/components/GitHubActionsFetcher.refactored.tsx](src/components/GitHubActionsFetcher.refactored.tsx) | 85 LOC | Refactored example (was 887) |
|
|
| [src/components/WorkflowRunCard.tsx](src/components/WorkflowRunCard.tsx) | 48 LOC | Reusable card component |
|
|
|
|
### Documentation: Quick References
|
|
| File | Length | Best For |
|
|
|------|--------|----------|
|
|
| [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md) | 185 LOC | Getting started in 5 minutes |
|
|
| [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md) | 350 LOC | Understanding the architecture |
|
|
| [TEAM_CHECKLIST.md](TEAM_CHECKLIST.md) | 320 LOC | Process and workflow |
|
|
|
|
### Documentation: Detailed Guides
|
|
| File | Location | Length | For |
|
|
|------|----------|--------|-----|
|
|
| REFACTORING_ENFORCEMENT_GUIDE.md | [docs/](docs/REFACTORING_ENFORCEMENT_GUIDE.md) | 320 LOC | Comprehensive reference |
|
|
| REFACTORING_STRATEGY.md | [docs/](docs/REFACTORING_STRATEGY.md) | 858 LOC | Detailed analysis & plans |
|
|
| REFACTORING_QUICK_REFERENCE.md | [docs/](docs/REFACTORING_QUICK_REFERENCE.md) | 430 LOC | Code examples & templates |
|
|
| REFACTORING_INDEX.md | [docs/](docs/REFACTORING_INDEX.md) | 412 LOC | Navigation hub |
|
|
|
|
### Documentation: Generated by Agent
|
|
| File | Location | Purpose |
|
|
|------|----------|---------|
|
|
| REFACTORING_DIAGRAMS.md | [docs/](docs/REFACTORING_DIAGRAMS.md) | Architecture visualizations |
|
|
| REFACTORING_SUMMARY.md | [docs/](docs/REFACTORING_SUMMARY.md) | Executive overview |
|
|
|
|
### Overview Documents
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | What was delivered, metrics, next steps |
|
|
|
|
---
|
|
|
|
## 🎓 Learning Paths
|
|
|
|
### Path 1: Quick Start (15 minutes)
|
|
1. Read [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md)
|
|
2. Run: `npx tsx /workspaces/metabuilder/scripts/enforce-size-limits.ts`
|
|
3. Browse: [src/hooks/](src/hooks/) and [src/components/](src/components/)
|
|
|
|
### Path 2: Developer Onboarding (1 hour)
|
|
1. Read [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md)
|
|
2. Read [docs/REFACTORING_ENFORCEMENT_GUIDE.md](docs/REFACTORING_ENFORCEMENT_GUIDE.md)
|
|
3. Study example: [src/components/GitHubActionsFetcher.refactored.tsx](src/components/GitHubActionsFetcher.refactored.tsx)
|
|
4. Check available hooks: [src/hooks/index.ts](src/hooks/index.ts)
|
|
|
|
### Path 3: Deep Dive (3 hours)
|
|
1. [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - Overview
|
|
2. [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md) - Architecture
|
|
3. [docs/REFACTORING_ENFORCEMENT_GUIDE.md](docs/REFACTORING_ENFORCEMENT_GUIDE.md) - Complete guide
|
|
4. [docs/REFACTORING_STRATEGY.md](docs/REFACTORING_STRATEGY.md) - Strategy & analysis
|
|
5. [docs/REFACTORING_QUICK_REFERENCE.md](docs/REFACTORING_QUICK_REFERENCE.md) - Code patterns
|
|
|
|
### Path 4: Team Lead/Manager (2 hours)
|
|
1. [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - What was done
|
|
2. [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md) - Overview
|
|
3. [TEAM_CHECKLIST.md](TEAM_CHECKLIST.md) - Process
|
|
4. [docs/REFACTORING_STRATEGY.md](docs/REFACTORING_STRATEGY.md) - Strategy
|
|
|
|
---
|
|
|
|
## 🔍 Find What You Need
|
|
|
|
### "I want to..."
|
|
|
|
**...understand the size limits**
|
|
→ [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md) + [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md)
|
|
|
|
**...run the size limit checker**
|
|
→ [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md#-how-to-check)
|
|
|
|
**...refactor my component**
|
|
→ [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md#-how-to-refactor-step-by-step)
|
|
|
|
**...use an existing hook**
|
|
→ [src/hooks/index.ts](src/hooks/index.ts)
|
|
|
|
**...create a new hook**
|
|
→ [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md#-how-to-refactor-step-by-step)
|
|
|
|
**...see a refactoring example**
|
|
→ [src/components/GitHubActionsFetcher.refactored.tsx](src/components/GitHubActionsFetcher.refactored.tsx)
|
|
|
|
**...understand the metrics**
|
|
→ [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md#size-limit-metrics)
|
|
|
|
**...set up CI/CD**
|
|
→ [docs/REFACTORING_ENFORCEMENT_GUIDE.md](docs/REFACTORING_ENFORCEMENT_GUIDE.md#-deployment-steps)
|
|
|
|
**...train the team**
|
|
→ [TEAM_CHECKLIST.md](TEAM_CHECKLIST.md)
|
|
|
|
**...understand the strategy**
|
|
→ [docs/REFACTORING_STRATEGY.md](docs/REFACTORING_STRATEGY.md)
|
|
|
|
**...get code examples**
|
|
→ [docs/REFACTORING_QUICK_REFERENCE.md](docs/REFACTORING_QUICK_REFERENCE.md)
|
|
|
|
---
|
|
|
|
## 📊 Quick Stats
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| **Lines of Code (LOC) Limit** | 150 per file |
|
|
| **Total Lines Limit** | 200 per file |
|
|
| **Max Nesting Depth** | 3 levels |
|
|
| **Max Exports** | 5-10 per file |
|
|
| **Max Function Params** | 5 parameters |
|
|
|
|
| Component | Before | After | Reduction |
|
|
|-----------|--------|-------|-----------|
|
|
| GitHubActionsFetcher | 887 LOC | 85 LOC | 90.4% |
|
|
| Hook Library | - | 280 LOC | - |
|
|
| Sub-components | - | ~76 LOC | - |
|
|
|
|
| Documentation | Lines |
|
|
|---|---|
|
|
| Root level guides | 1,235 LOC |
|
|
| docs/ folder guides | 3,700+ LOC |
|
|
| **Total** | **4,935+ LOC** |
|
|
|
|
---
|
|
|
|
## 🚀 Quick Commands
|
|
|
|
```bash
|
|
# Check size limits
|
|
npx tsx /workspaces/metabuilder/scripts/enforce-size-limits.ts
|
|
|
|
# View report
|
|
cat size-limits-report.json
|
|
|
|
# List available hooks
|
|
cat src/hooks/index.ts
|
|
```
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
**Getting help?** Check in this order:
|
|
1. [REFACTORING_QUICK_START.md](REFACTORING_QUICK_START.md) - Quick answers
|
|
2. [ARCHITECTURE_DIAGRAM.md](ARCHITECTURE_DIAGRAM.md) - Visual explanations
|
|
3. [docs/REFACTORING_ENFORCEMENT_GUIDE.md](docs/REFACTORING_ENFORCEMENT_GUIDE.md) - Detailed reference
|
|
4. [docs/REFACTORING_QUICK_REFERENCE.md](docs/REFACTORING_QUICK_REFERENCE.md) - Code examples
|
|
5. Example code in [src/components/](src/components/) and [src/hooks/](src/hooks/)
|
|
|
|
---
|
|
|
|
## ✅ Verification Checklist
|
|
|
|
Have you...?
|
|
- [ ] Read REFACTORING_QUICK_START.md
|
|
- [ ] Run the size limit checker
|
|
- [ ] Reviewed the hook examples
|
|
- [ ] Looked at the refactored component
|
|
- [ ] Understand the metrics
|
|
- [ ] Know where to find documentation
|
|
- [ ] Ready to refactor your code
|
|
|
|
---
|
|
|
|
## 📋 File Structure
|
|
|
|
```
|
|
/workspaces/metabuilder/
|
|
├── REFACTORING_QUICK_START.md ← Start here
|
|
├── IMPLEMENTATION_SUMMARY.md ← Overview
|
|
├── ARCHITECTURE_DIAGRAM.md ← Visual guide
|
|
├── TEAM_CHECKLIST.md ← Team process
|
|
│
|
|
├── scripts/
|
|
│ └── enforce-size-limits.ts ← Tool
|
|
│
|
|
├── src/
|
|
│ ├── hooks/
|
|
│ │ ├── useGitHubFetcher.ts
|
|
│ │ ├── useAutoRefresh.ts
|
|
│ │ ├── useFileTree.ts
|
|
│ │ ├── useCodeEditor.ts
|
|
│ │ └── index.ts
|
|
│ └── components/
|
|
│ ├── GitHubActionsFetcher.refactored.tsx
|
|
│ └── WorkflowRunCard.tsx
|
|
│
|
|
├── docs/
|
|
│ ├── REFACTORING_ENFORCEMENT_GUIDE.md
|
|
│ ├── REFACTORING_STRATEGY.md
|
|
│ ├── REFACTORING_QUICK_REFERENCE.md
|
|
│ ├── REFACTORING_INDEX.md
|
|
│ ├── REFACTORING_DIAGRAMS.md
|
|
│ └── REFACTORING_SUMMARY.md
|
|
│
|
|
├── .github/workflows/
|
|
│ └── size-limits.yml ← CI/CD
|
|
│
|
|
└── .git/hooks/
|
|
└── pre-commit ← Local check
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: December 25, 2025
|
|
**Status**: 🟢 Complete & Production Ready
|
|
**Version**: 1.0
|