SonarJS Complexity Metrics Integration
Status: Planned (Phase 0 ready to begin)
Repository: arda-frontend-app
Prerequisite: None — can start immediately
Source proposal: workspace/projects/_planning/fe-quality-metrics/sonarjs-integration-proposal.md
Integrate eslint-plugin-sonarjs into the arda-frontend-app development workflow to surface cognitive and cyclomatic complexity metrics. The rollout uses a ratcheting strategy: generous initial thresholds that tighten over time.
Baseline
Section titled “Baseline”The initial scan on the jmpicnic/stryker-exp branch found 453 problems (316 errors, 137 warnings) concentrated in 5 hotspot files. The two worst files have cognitive complexity scores over 80.
Rollout Phases
Section titled “Rollout Phases”| Phase | Timeframe | Cognitive threshold | Cyclomatic threshold | CI max-warnings | Effect |
|---|---|---|---|---|---|
| 0 — Baseline | Week 1 | warn @ 25 | warn @ 20 | 9,999 | Install, measure, educate; CI always green |
| 1 — Awareness | Month 1 | warn @ 25 | warn @ 20 | 9,999 | Developers see warnings in IDE and PR artifacts |
| 2 — Soft gate | Month 2 | warn @ 20 | warn @ 15 | 500 | PRs with >500 warnings fail |
| 3 — Hard gate | Quarter 2 | warn @ 15 | warn @ 10 | 300 | Meaningful enforcement; hotspots must be resolved first |
| 4 — Steady state | Ongoing | warn @ 15 | warn @ 10 | Ratchet -10/sprint | Monotonically decreasing ceiling |
Configuration
Section titled “Configuration”Four rules only — no preset (avoids inheriting ~20 rules needing audit):
sonarjs/cognitive-complexity(warn @ 25)sonarjs/cyclomatic-complexity(warn @ 20)sonarjs/no-nested-conditional(warn)sonarjs/no-identical-functions(warn)
A dedicated eslint.complexity.mjs config file runs the complexity-only analysis in CI to keep the job fast and focused.
CI Integration
Section titled “CI Integration”A new complexity job runs on every PR:
- Identifies changed source files via
git diff. - Runs complexity analysis on changed files only (does not penalize PRs for pre-existing debt).
- Uploads a complexity report artifact (retained 90 days) with per-file violation counts and worst scores.
- The full-codebase snapshot is captured for trend tracking but does not gate PRs.
Hotspot Files (must be addressed before Phase 2)
Section titled “Hotspot Files (must be addressed before Phase 2)”| File | Cognitive max | Cyclomatic max | Priority |
|---|---|---|---|
src/app/items/page.tsx | 111 | 81 | P1 |
src/app/order-queue/page.tsx | 89 | 94 | P1 |
src/components/scan/MobileScanView.tsx | ~40 | ~40 | P2 |
src/components/items/ItemFormPanel.tsx | ~30 | ~30 | P2 |
src/components/table/columnPresets.tsx | ~25 | ~25 | P3 |
P1 hotspots require component decomposition before Phase 2 thresholds take effect. See Complexity Hotspot Remediation.
| # | Description | Persona |
|---|---|---|
| 1 | Install eslint-plugin-sonarjs, update eslint.config.mjs | Front End Engineer |
| 2 | Create eslint.complexity.mjs | Front End Engineer |
| 3 | Add npm scripts and Makefile targets | Front End Engineer |
| 4 | Create scripts/complexity-summary.mjs | Front End Engineer |
| 5 | Add complexity CI job (required check, --max-warnings 9999) | DevOps Engineer |
| 6 | Add reports/complexity/ to .gitignore | Front End Engineer |
| 7 | Write developer training document | Technical Writer |
| 8 | Create complexity-metrics agent skill | Principal Engineer |
| 9 | Integrate skill into agent personas | Principal Engineer |
| 10 | Run baseline scan, commit snapshot | Front End Engineer |
| 11 | Team walkthrough session | All |
Copyright: © Arda Systems 2025-2026, All rights reserved