complexity

You are computing cyclomatic complexity (CC) — the number of linearly independent paths through a function. CC of 1 = straight-line code, 5 = moderate, 10 = at the limit of "manageable", 15+ = needs refactoring.

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/pmd.sh"
APEX_SRC="$(sf_config_get '.paths.apexSource' "$ENV")"
LWC_SRC="$(sf_config_get '.paths.lwcSource' "$ENV")"
TEST_SUFFIX="$(sf_config_get '.naming.apex.testSuffix' "$ENV")"

PMD has built-in cyclomatic complexity rules — we delegate Apex CC to it. For LWC (JS), we count manually since PMD doesn't analyze JS.

Input

$ARGUMENTS:

• (empty) — scan everything
• apex — Apex only
• lwc — LWC JS only
• --threshold <n> — flag complexity above N (default 10)
• --ci / --format json|sarif / --out <path>

Steps

Apex (via PMD)

pmd_run check \
  --dir "$APEX_SRC" \
  --rulesets "category/apex/design.xml" \
  --format json \
  --report-file /tmp/complexity.pmd.json \
  --no-progress

Filter the PMD output to rules:

• CyclomaticComplexity — primary
• CognitiveComplexity — secondary (related but distinct)
• ExcessiveClassLength, ExcessiveMethodLength — overflow indicators

Convert each to internal finding shape with ruleId: "CPX-CYCLOMATIC" (or CPX-COGNITIVE, etc.).

LWC JS (heuristic counter)

For each .js file under ${LWC_SRC} (excluding __tests__):

• For each function (declaration or arrow assigned to a property), count the following as +1:
  • if, else if
  • case in a switch
  • for, while, do
  • Ternary ? :
  • Logical &&, || (short-circuit increases path)
  • catch block
  • Each top-level return after the first

Base complexity = 1; cap at 50 for sanity (anything beyond is pathological).

Report findings with ruleId: "CPX-LWC-CYCLOMATIC", severity:

• 11–15: warning
• 16+: error

Output

Default Markdown:

# Complexity Report: <project.name>

Threshold: 10
Apex methods analyzed: 412 (production, excluding tests)
LWC JS functions analyzed: 287
Run at: 2026-04-28T15:15:00Z

## Apex hotspots (top 10)

| File | Method | Cyclomatic | Cognitive | Length |
|------|--------|------------|-----------|--------|
| force-app/.../OrderProcessor.cls | processBulk | 22 ⚠️ | 31 ⚠️ | 145 lines |
| force-app/.../LegacyImporter.cls | importBatch | 18 ⚠️ | 26 ⚠️ | 110 lines |
| ...

## LWC hotspots (top 10)

| File | Function | Cyclomatic |
|------|----------|------------|
| force-app/.../acmeOrderForm/acmeOrderForm.js | handleSave | 13 ⚠️ |
| ...

## Refactoring suggestions
- `OrderProcessor.processBulk` (CC 22): extract per-record logic into a helper; the 22 paths likely collapse to a single switch over status
- `acmeOrderForm.handleSave` (CC 13): split validation, persistence, and side-effects into separate methods

## Distribution
- ≤5 (good):     312 methods (76%)
- 6–10 (ok):      87 methods (21%)
- 11–15 (warn):   11 methods  (3%)
- 16+ (error):     2 methods  (1%)

CI: SARIF per finding with severity mapped from threshold bands.

Exit codes

• 0 — no findings above threshold
• 1 — any finding above threshold
• 2 — PMD failed to run

Rules

• Threshold is configurable. Some teams accept 15; tighter teams set 8. Default 10 is the conventional middle
• Don't analyze test classes. They legitimately have many setup branches
• PMD-driven for Apex. Don't reimplement CC counting — PMD's tested implementation is the right call
• Heuristic for LWC. Without an AST parser available, the regex-based count is approximate. Flag the count alongside "approx" so the user knows
• No auto-refactor. This is a report; the user picks what to refactor

Consumers

• /argo:code-review rolls hotspots into the LWC/Apex sections
• @architect consults complexity before approving large additions to existing methods