tl-complexity-assessment（TL 复杂性评估）

tl-complexity-assessment

Find the files that need to be split up. Get a ranked, evidence-based list of complexity hotspots with specific refactoring recommendations.

Quick Start

For experienced users — run the scanner and get a report:

# Bash
./scripts/complexity-scan.sh src/

# PowerShell
.\scripts\complexity-scan.ps1 -TargetDir src/

For guided assessment — follow the phases below.

When to Use

• "find complex files"
• "what needs to be split up"
• "assess complexity" / "code health check"
• "find monoliths" / "find god files"
• "identify refactoring candidates"
• "this file is too big"
• Before major refactoring efforts
• When onboarding to a new codebase
• Sprint planning for tech debt reduction

Do Not Use When

• Looking for bugs (use debugging skills instead)
• Assessing security vulnerabilities (use security audit)
• Reviewing code style (use linting/formatting tools)
• File is already small and focused (<150 lines, single responsibility)

Outcomes

• Analysis: Ranked list of complexity hotspots with evidence and recommendations
• Decision: Which files/modules to refactor first (ROI-based prioritization)
• Artifact: Optional findings register (markdown) for tracking remediation
• Next Steps: Clear refactoring recommendations for each finding

The Iron Law

NO COMPLEXITY CLAIMS WITHOUT EVIDENCE

Every finding must include file path, line count or metric, and specific observation.

What Good Looks Like

❌ BAD: "UserService.ts is too complex and should be refactored"

✅ GOOD: "UserService.ts (847 lines, 23 exports) mixes 4 concerns:
   - Authentication (lines 1-150)
   - Validation (lines 151-320)
   - API calls (lines 321-600)
   - Formatting (lines 601-847)

   Recommendation: Split into auth.ts, validation.ts, api.ts, formatters.ts
   Effort: E2 (4-8 hours) | Impact: High (imported by 12 files)"

Assessment Categories

Category 1: Size Indicators

Category 2: Responsibility Indicators

Category 3: Coupling Indicators

Category 4: Cyclomatic Complexity Proxies

Category 5: React-Specific Smells

Category 6: Structural Smells

Assessment Phases

Phase 1: Automated Discovery

Run these commands to gather metrics. Adapt paths to your project structure.

Find large files:

find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -rn | head -30

Count exports per file:

rg "^export " --type ts -c | sort -t: -k2 -rn | head -20

Count imports per file:

rg "^import " --type ts -c | sort -t: -k2 -rn | head -20

Find god files:

rg -l "utils|helpers|common|shared" --type ts --glob "!node_modules" | head -20

Find React components with many hooks:

rg "useEffect\(" --type tsx -c | sort -t: -k2 -rn | head -20

Find deeply nested conditionals:

rg "if.*if.*if" --type ts -l | head -20

Find files with many functions:

rg "^(export )?(async )?(function |const \w+ = )" --type ts -c | sort -t: -k2 -rn | head -20

Phase 2: Manual Analysis

For each candidate file from Phase 1:

1. Read the file - Understand what it does
2. Identify responsibilities - List distinct concerns
3. Check coupling - What does it import from? What imports it?
4. Assess cohesion - Do all parts serve a single purpose?
5. Document evidence - File path, line count, specific observations

Phase 3: Scoring

Score each finding 0-10:

Score Formula:

Score = (Severity × 2) + (Impact × 2) + (Effort_Inverse)

Where:

• Severity: 1 (Low) to 3 (Critical)
• Impact: 1 (isolated) to 3 (affects many files)
• Effort_Inverse: 3 (easy fix) to 1 (hard fix)

Phase 4: Report

For each finding, report:

### [Rank] File: `path/to/file.ts`

**Score:** 8/10 | **Severity:** High | **Effort:** Medium

**Metrics:**
- Lines: 847
- Exports: 23
- Imports: 18 (from 6 domains)

**Observations:**
- Contains 4 unrelated responsibilities: auth, validation, API calls, formatting
- 3 useEffect hooks managing different concerns
- Imported by 12 other files

**Recommendation:**
Split into:
- `auth.ts` - Authentication utilities
- `validation.ts` - Form validation
- `api.ts` - API client functions
- `formatters.ts` - Display formatting

**Evidence:**
Lines 1-150: Auth functions
Lines 151-320: Validation schemas
Lines 321-600: API calls
Lines 601-847: Formatting utilities

Priority Matrix

ROI = Severity × (4 - Effort)

🔥 = Address first (ROI ≥ 9)

Red Flags - Stop and Reassess

If you catch yourself:

• Claiming "this file is complex" without metrics
• Recommending splits without identifying responsibilities
• Skipping files because they "look fine"
• Using vague terms like "too big" or "messy"
• Recommending refactors without considering import impact

Return to Phase 1. Gather evidence.

Rationalizations (Do Not Skip)

Time-Boxing Guidelines

When time expires: Document what you found. Mark incomplete areas with next actions.

Output Format

Provide a summary table followed by detailed findings:

## Complexity Assessment Summary

| Rank | File | Score | Severity | Recommendation |
|------|------|-------|----------|----------------|
| 1 | `src/utils/helpers.ts` | 9 | Critical | Split into 4 domain files |
| 2 | `src/components/Dashboard.tsx` | 8 | High | Extract 3 sub-components |
| 3 | `src/api/client.ts` | 7 | High | Separate by API domain |

### Top Finding Details
[Detailed findings for top 5-10 items]

Example Real Output

See Example Output for a worked-through assessment report (summary table, per-file score, observations, recommendations, evidence).

What To Do After Assessment

Once you have findings, here's how to act on them:

Immediate (This Sprint)

1. Fix 🔥 Critical findings (ROI ≥ 9) - These block velocity
2. Run tl-knip to remove dead exports before splitting
3. Add tests for files you're about to split

Plan (Next Sprint)

1. Create tickets for High-priority findings (score 7-8)
2. Group related splits (e.g., all API files together)
3. Estimate using the Effort column

Monitor (Ongoing)

1. Re-run assessment monthly to catch new complexity
2. Add complexity checks to PR reviews
3. Set team threshold: "No new files over 300 lines without review"

Cognitive vs Cyclomatic Complexity

See Cognitive Complexity for the difference between cyclomatic and cognitive complexity, scoring rules, and ESLint/SonarJS integration.

Code Review Metrics

See Code Review Metrics for optimal PR size thresholds, review time budgets, and a CI complexity-gate workflow example.

Verification Checklist

Before completing assessment:

• Ran automated discovery commands
• Every finding has file path and line count
• Every finding has specific observations (not vague)
• Responsibilities identified for each split recommendation
• Effort estimated for each recommendation
• Priority calculated using ROI formula
• Time-boxing respected
• Summary table provided with top findings

Skill Resources

Automated Discovery

Run the scanner script for quick assessment:

# Bash
./scripts/complexity-scan.sh src/

# PowerShell
.\scripts\complexity-scan.ps1 -TargetDir src/

Reference Documentation

Load these references when deeper analysis is needed for a specific category.

Related Skills

• tl-knip - Find unused exports (reduces false positives in export counts)
• codebase-audit - Broader code health assessment
• ui-audit - UI-specific complexity and drift detection
• semgrep/skills/code-security - Security vulnerability detection (complementary to structural complexity)

References

Quilted Sources

• trailofbits/skills/code-maturity-assessor — Assessment framework
• obra/superpowers/systematic-debugging — Iron Law pattern
• obra/superpowers/verification-before-completion — Evidence principles
• rmyndharis/antigravity-skills/code-refactoring-refactor-clean — SOLID assessment

Official Skills

• semgrep/skills/semgrep — Static analysis and custom rule creation
• semgrep/skills/code-security — Security vulnerability patterns
• jwynia/agent-skills/code-review — Review metrics

First-Party Documentation

• ESLint Complexity Rule — Cyclomatic complexity linting
• SonarQube Cognitive Complexity — Cognitive complexity definition
• Semgrep Rule Writing — Custom complexity rules
• TypeScript Compiler API — AST analysis

Academic/Industry

• Cognitive Complexity Paper — Original SonarSource definition
• Code Complete 2 — McConnell complexity guidance