agentsqripts/lib/srp-violations/LIMITATIONS.md

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

# SRP Analyzer Limitations

## Fundamental Static Analysis Constraints

The SRP analyzer enforces a strict "one function per file" rule, but this mechanical approach has significant limitations:

### 1. Cannot Distinguish Function Purpose
Static analysis sees all functions equally:
```javascript
// To the analyzer, these are both just "functions":
function validateEmail(email) { return email.includes('@'); }  // Simple helper
function processPayment(order) { /* 100 lines of logic */ }    // Complex business logic
```

### 2. Cannot Understand Semantic Relationships
The tool cannot determine if functions belong together:
```javascript
// These logically related functions are forced apart:
function openDatabase() { }
function closeDatabase() { }
function queryDatabase() { }
```

### 3. Mechanical Rule Enforcement
- Counts functions, not complexity
- Ignores context (test files, configs, utilities)
- Creates file explosion (we went from ~200 to 341 files)

### 4. What Static Analysis CAN Do
- Count functions, lines, parameters
- Detect patterns (but not meaning)
- Enforce consistent structure

### 5. What It CANNOT Do
- Understand "helper" vs "core" functions
- Determine function importance
- Recognize logical groupings
- Apply human judgment

## The Trade-off

Strict SRP (one function per file) provides:
- ✅ Absolute consistency
- ✅ Clear boundaries
- ✅ Easy to enforce

But costs:
- ❌ File navigation complexity
- ❌ Separated related functions
- ❌ Lost context
- ❌ Overhead of imports/exports

## Recommendation

Consider the SRP score as a guideline, not gospel. High scores indicate files that *might* benefit from splitting, but human judgment is essential to determine if functions truly belong together.