analyze

Scan a legacy codebase and generate suggested bounded contexts, complexity tiers, and hotspot identification.

Usage

npx modernizespec analyze [options]

What It Does

1. Scans the project directory for source files
2. Analyzes module boundaries (directory structure, import patterns, naming conventions)
3. Computes file-level metrics (LOC, function count, import count)
4. Identifies God-classes and complexity hotspots
5. Suggests bounded context groupings
6. Outputs updated domains.json and complexity.json

Options

Flag	Description	Default
--dir <path>	Directory to analyze	Current directory
--language <lang>	Source language	Auto-detected
--framework <name>	Framework (affects analysis heuristics)	Auto-detected
--output <format>	Output format: files, json, stdout	files
--dry-run	Show suggestions without writing files	Write to disk
--god-class-threshold <n>	LOC threshold for God-class detection	2000

Examples

Analyze Current Project

npx modernizespec analyze

Dry Run (Preview Only)

npx modernizespec analyze --dry-run

Analyze with Custom Threshold

npx modernizespec analyze --god-class-threshold 1500

Analyze Specific Directory

npx modernizespec analyze --dir /path/to/legacy-project --language python

Output

When --output files (default), the command updates:

• .agents/modernization/domains.json — Suggested bounded contexts
• .agents/modernization/complexity.json — Hotspots and tiers

When --output json, the analysis is printed to stdout as JSON for piping.

Analysis Heuristics

Module Detection

The analyzer looks for:

• Top-level directories as potential bounded contexts
• modules.txt or equivalent framework manifests
• Package/namespace boundaries
• Import clustering (files that import each other tend to belong together)

Complexity Assessment

Metric	Calculation
LOC	Line count (excluding blanks and comments)
Function count	AST or regex-based function/method detection
Import count	Direct import statements per file
Cyclomatic complexity	Branch count approximation

Tier Assignment

Modules are assigned to tiers based on:

Factor	Tier 1 (Extract Now)	Tier 2 (Extract With Care)	Tier 3 (Defer)
External coupling	Low (< 0.2)	Medium (0.2 - 0.5)	High (> 0.5)
God-classes	None	Some (decomposable)	Central (blocking)
Framework coupling	Low	Moderate	Deep

Limitations

• Analysis is heuristic-based, not semantically precise
• Framework-specific patterns may not be detected without the --framework flag
• Cross-file dependency analysis is approximate (based on imports, not runtime calls)
• Results should be reviewed and adjusted by someone with domain knowledge

See Also

• domains.json Specification — What the analyzer generates
• complexity.json Specification — Hotspot format details