Skip to content

Commit f0e020d

Browse files
anthonydmaysanthonydmays
authored
chore: refactors grader project for performance and maintainability (code-differently#617)
* chore: refactors monolith script into multiple files Signed-off-by: Anthony D. Mays <[email protected]> * fix: ensures function exports work correctly on gas runtime Signed-off-by: Anthony D. Mays <[email protected]> * chore: restores project_oop readme Signed-off-by: Anthony D. Mays <[email protected]> --------- Signed-off-by: Anthony D. Mays <[email protected]>
1 parent 6234bf8 commit f0e020d

File tree

14 files changed

+7053
-4391
lines changed

14 files changed

+7053
-4391
lines changed

‎lib/javascript/grader/.clasp.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
1-
{"scriptId":"17mrtU0kXm3s51qeefzeBH6V12yzNztLayWorp8pTOMW25QHscqIkiU3L","rootDir":"/Users/anthonymays/source/forks/code-society-25-2/lib/javascript/grader"}
1+
{
2+
"scriptId": "17mrtU0kXm3s51qeefzeBH6V12yzNztLayWorp8pTOMW25QHscqIkiU3L",
3+
"rootDir": "./dist"
4+
}

‎lib/javascript/grader/GRADING_ENHANCEMENT.md‎

Lines changed: 0 additions & 211 deletions
This file was deleted.

‎lib/javascript/grader/docs/v1.1-REFACTOR.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# GitHub Grader - Modular Architecture
2+
3+
This document outlines the refactored modular structure of the GitHub Grader Google Apps Script system.
4+
5+
## 📁 File Structure
6+
7+
```
8+
src/
9+
├── config.ts # Configuration constants
10+
├── types.ts # TypeScript interface definitions
11+
├── github-api.ts # GitHub API service layer
12+
├── sheets-service.ts # Google Sheets operations
13+
├── grading-service.ts # OpenAI integration & grading logic
14+
├── utils.ts # Utility functions and helpers
15+
├── main-refactored.ts # Main orchestration & UI (NEW VERSION)
16+
└── main.ts # Original monolithic version (LEGACY)
17+
```
18+
19+
## 🏗️ Architecture Overview
20+
21+
### 1. **config.ts** - Central Configuration
22+
- **Purpose**: All configuration constants in one place
23+
- **Contains**: Sheet names, column mappings, API endpoints, cache settings
24+
- **Benefits**: Easy to modify settings, environment-specific configs
25+
26+
### 2. **types.ts** - Type Definitions
27+
- **Purpose**: TypeScript interfaces and type safety
28+
- **Contains**: Data structures, API response types, function signatures
29+
- **Benefits**: Better IntelliSense, compile-time error checking, documentation
30+
31+
### 3. **github-api.ts** - GitHub Integration
32+
- **Purpose**: All GitHub API interactions with caching
33+
- **Contains**: PR fetching, file retrieval, review creation, grading instructions
34+
- **Benefits**: Rate limiting protection, request caching, API error handling
35+
36+
### 4. **sheets-service.ts** - Google Sheets Operations
37+
- **Purpose**: Optimized spreadsheet operations with caching
38+
- **Contains**: Data reading/writing, student lookup, batch updates
39+
- **Benefits**: Reduced API calls, intelligent caching, better performance
40+
41+
### 5. **grading-service.ts** - AI-Powered Grading
42+
- **Purpose**: OpenAI integration and intelligent analysis
43+
- **Contains**: ChatGPT analysis, diff processing, review generation
44+
- **Benefits**: Content optimization, token management, fallback strategies
45+
46+
### 6. **utils.ts** - Utility Functions
47+
- **Purpose**: Common helper functions and utilities
48+
- **Contains**: String processing, performance monitoring, validation
49+
- **Benefits**: Code reuse, consistent logging, debugging tools
50+
51+
### 7. **main-refactored.ts** - Orchestration Layer
52+
- **Purpose**: Main workflow coordination and UI
53+
- **Contains**: Sync orchestration, menu creation, setup functions, testing
54+
- **Benefits**: Clean separation of concerns, easier maintenance
55+
56+
## ⚡ Performance Improvements
57+
58+
### Caching Strategy
59+
- **Sheet Data**: 5-minute cache for spreadsheet data
60+
- **API Responses**: 10-minute cache for GitHub API calls
61+
- **Student Lookup**: In-memory map for O(1) student lookups
62+
63+
### Batch Operations
64+
- **Sheet Updates**: Batch multiple cell updates into fewer API calls
65+
- **PR Processing**: Intelligent filtering to avoid reprocessing
66+
- **Time Limits**: Respects Google Apps Script execution limits
67+
68+
### Resource Optimization
69+
- **Content Limiting**: Intelligent truncation of large diffs for AI analysis
70+
- **Early Termination**: Stops processing when limits are reached
71+
- **Smart Filtering**: Processes only unprocessed PRs
72+
73+
## 🎯 Benefits of Modular Architecture
74+
75+
### Development Benefits
76+
- **Easier Debugging**: Isolated components for focused testing
77+
- **Better Testing**: Each module can be unit tested independently
78+
- **Team Collaboration**: Multiple developers can work on different modules
79+
- **Code Reuse**: Services can be used in other Apps Script projects
80+
81+
### Maintenance Benefits
82+
- **Focused Changes**: Modifications only affect relevant modules
83+
- **Clear Dependencies**: Import statements show relationships
84+
- **Consistent Patterns**: Standardized error handling and logging
85+
- **Documentation**: Each module has clear responsibility
86+
87+
### Performance Benefits
88+
- **Reduced Memory Usage**: Only load needed functionality
89+
- **Better Caching**: Module-specific caching strategies
90+
- **Optimized API Calls**: Centralized request management
91+
- **Resource Management**: Better handling of execution limits
92+
93+
## 🧪 Testing Strategy
94+
95+
### Module Testing
96+
```javascript
97+
// Test individual services
98+
function testGitHubApi() {
99+
const prs = GitHubApiService.getRecentPullRequests();
100+
console.log(`Found ${prs.length} PRs`);
101+
}
102+
103+
function testSheetsService() {
104+
const student = SheetsService.lookupStudentName('testuser');
105+
console.log(`Student lookup: ${student}`);
106+
}
107+
```
108+
109+
### Integration Testing
110+
```javascript
111+
// Test full workflow with single PR
112+
function testSinglePR(prNumber: number) {
113+
const pr = GitHubApiService.getPullRequest(prNumber);
114+
const result = processPullRequest(pr);
115+
console.log(result);
116+
}
117+
```
118+
119+
## 📈 Monitoring and Debugging
120+
121+
### Performance Monitoring
122+
- **Execution Timing**: Each major operation is timed
123+
- **Cache Hit Rates**: Monitor cache effectiveness
124+
- **Error Tracking**: Centralized error logging with context
125+
126+
### Debug Tools
127+
- **Cache Clearing**: Manual cache invalidation
128+
- **Test Functions**: Individual component testing
129+
- **Verbose Logging**: Detailed execution traces in development mode
130+
131+
## 🔧 Configuration
132+
133+
### Environment Setup
134+
```javascript
135+
// Set development mode
136+
PropertiesService.getScriptProperties().setProperty("DEV_MODE", "true");
137+
138+
// Configure API keys
139+
setupGitHubToken(); // Interactive setup
140+
setupOpenAIKey(); // Interactive setup
141+
```
142+
143+
### Custom Configuration
144+
Modify `config.ts` for environment-specific settings:
145+
- Sheet names and column mappings
146+
- Processing limits and timeouts
147+
- Cache durations
148+
- API endpoints
149+
150+
## 🚀 Next Steps
151+
152+
1. **Add Unit Tests**: Create comprehensive test suite for each module
153+
2. **Performance Tuning**: Monitor and optimize based on actual usage
154+
3. **Feature Extensions**: Add new capabilities using the modular structure
155+
4. **Documentation**: Expand documentation as the system grows
156+
157+
This modular architecture provides a solid foundation for scaling the GitHub Grader system while maintaining performance and reliability.

0 commit comments

Comments
 (0)