complexity.json

complexity.json captures the extraction difficulty of each module. It organizes modules into tiers based on coupling, boundary clarity, and business value, and identifies specific files that are complexity hotspots.

Full Example

{
  "tiers": [
    {
      "tier": 1,
      "label": "Extract Now",
      "description": "Low coupling, clear boundaries, high business value",
      "modules": ["Mode of Payment", "Tax Calculator", "Bank Reconciliation"]
    },
    {
      "tier": 2,
      "label": "Extract With Care",
      "description": "Moderate coupling, needs ACL at boundaries",
      "modules": ["Payment Entry", "Journal Entry", "Cost Center"]
    },
    {
      "tier": 3,
      "label": "Defer",
      "description": "Deep framework coupling, high risk",
      "modules": ["Sales Invoice", "Stock Entry", "Manufacturing"]
    }
  ],
  "hotspots": [
    {
      "file": "controllers/accounts_controller.py",
      "loc": 4412,
      "functions": 168,
      "cyclomaticComplexity": "very-high",
      "recommendation": "Decompose before extraction"
    },
    {
      "file": "stock/doctype/stock_entry/stock_entry.py",
      "loc": 4149,
      "functions": 120,
      "cyclomaticComplexity": "high",
      "recommendation": "Extract with dedicated parity tests"
    },
    {
      "file": "accounts/doctype/payment_entry/payment_entry.py",
      "loc": 3559,
      "functions": 95,
      "cyclomaticComplexity": "high",
      "recommendation": "Extract with ACL for multi-currency"
    }
  ]
}

Interactive Visualization

Field Reference

tiers Array

Each entry defines an extraction tier:

Field	Type	Required	Description
tier	number	Yes	Tier number (1 = easiest to extract, 3 = hardest)
label	string	Yes	Human-readable label
description	string	Yes	What characterizes this tier
modules	string[]	Yes	Modules in this tier

hotspots Array

Each entry identifies a high-complexity file:

Field	Type	Required	Description
file	string	Yes	File path relative to project root
loc	number	Yes	Lines of code
functions	number	Yes	Number of functions/methods
cyclomaticComplexity	string	Yes	Complexity rating: "low", "medium", "high", "very-high"
recommendation	string	Yes	What to do about this file before or during extraction

Tier Classification Criteria

Tier 1: Extract Now

• Low external coupling (< 0.2)
• Clear module boundaries
• High business value relative to complexity
• Few or no God-classes
• Minimal framework coupling

Tier 2: Extract With Care

• Moderate external coupling (0.2 - 0.5)
• Boundaries exist but need Anti-Corruption Layer
• Requires careful dependency analysis
• May contain God-classes that need decomposition first

Tier 3: Defer

• High external coupling (> 0.5)
• Deep framework entanglement
• Cross-cutting concerns span multiple modules
• Extraction risk is high without prior Tier 1/2 work

Hotspot Thresholds

Metric	Threshold	Classification
Lines of code	> 2,000	God-class candidate
Functions per file	> 100	Complexity hotspot
Cyclomatic complexity	> 50 per function avg	Very high
Incoming dependencies	> 20 files	High blast radius

Agent Behavior

When an agent encounters a file in the hotspots list:

1. Check the recommendation field before making changes
2. If recommendation says “Decompose before extraction” — do not attempt direct extraction
3. If the file is in a Tier 3 module — check extraction-plan.json for sequencing constraints

Next Steps

• extraction-plan.json — Phased extraction sequence
• Complexity Heatmap — Interactive visualization