Code Quality Improvement Goals - March 2026

[github-actions]

Monthly code quality tracking report for azlin Python codebase.

Analysis Date: 2026-03-23
Scope: src/, scripts/, benchmarks/ (4,704 lines across 18 files, 122 functions)

---

📊 Overall Quality Scorecard

Metric	Value	Grade
Avg cyclomatic complexity	4.09	A
Functions with docstrings	113/122 (92%)	A
Functions with return types	82/122 (67%)	B
TODO/FIXME debt	0	A
Critical complexity (>20)	1 function	⚠️
Deeply nested files (>4)	6 files	⚠️

---

🔴 Critical Issues (Block)

1. scripts/doc_sync.py::main() — Complexity E (38)

This single function exceeds the "block" threshold of 20 by 90%. It is also 165 lines long, has 7 parameters, and reaches nesting depth 7.

• File: scripts/doc_sync.py, line 71
• Action: Split into smaller, single-responsibility functions

# Current: one main() does everything
def main(sync_all, command, output_dir, help_output_dir, ...):  # 165 lines, complexity 38

# Target: orchestrator delegates to focused helpers
def main(...):           # <20 lines, orchestrates
def _sync_command(...):  # handles single command sync
def _validate_sync(...): # handles validation

---

⚠️ Warnings (Refactor Recommended)

2. Long Functions (>50 lines) — 18 occurrences

Function	File	Lines
generate_concepts()	scripts/generate_docs.py	312
generate_first_vm()	scripts/generate_docs.py	296
main()	scripts/doc_sync.py	165
generate_quickstart()	scripts/generate_docs.py	135
_compare_commands()	scripts/validate_documentation.py	91
_download_from_release()	src/azlin/rust_bridge.py	68
validate()	scripts/validate_documentation.py	66
print_summary()	benchmarks/benchmark_parallel_vm_list.py	66
(10 more)		51–61

Top priority: generate_docs.py functions (312, 296, 135 lines) — these are documentation generators but could extract repeated template patterns.

3. Deep Nesting (>4 levels) — 6 files

File	Max Depth
scripts/doc_sync.py	7
scripts/extract_help.py	5
scripts/validate_documentation.py	5
scripts/cli_documentation/extractor.py	5
src/azlin/rust_bridge.py	4
scripts/audit_key_operations.py	4

4. Type Hint Coverage — 9% fully typed

Only 11 of 122 functions have both parameter and return annotations. The scripts/ directory is largely untyped. While Pyright strict mode covers src/ (the core package), the scripts and benchmarks have no enforced type checking.

Note: The 9% figure counts self as an unannotated param for instance methods. Effective coverage for non-self params is higher, but return types (67%) still leave 33% uncovered.

5. Maintainability Index — 3 files below 50

File	MI Score
scripts/validate_documentation.py	42.77
scripts/extract_help.py	43.41
scripts/test_audit_key_operations.py	47.78
src/azlin/rust_bridge.py	49.84

Files scoring below 50 are approaching "needs major refactoring" territory.

---

✅ Strengths

• Zero TODO/FIXME debt — clean codebase with no deferred work markers
• Excellent docstring coverage — 92% of functions documented
• Low average complexity — 4.09 overall (A grade)
• Strong core package quality — src/azlin/__init__.py scores MI 100.00
• Pre-commit quality gates — Ruff + Pyright strict on src/ enforces quality at commit time

---

📋 Refactoring Checklist

High Priority

• Split scripts/doc_sync.py::main() (complexity 38 → target <10 per function)
• Reduce nesting in scripts/doc_sync.py (depth 7 → target ≤3)

Medium Priority

• Extract template helpers from scripts/generate_docs.py (312-line and 296-line functions)
• Refactor scripts/validate_documentation.py::_compare_commands() (91 lines, complexity 15)
• Reduce nesting in scripts/extract_help.py and scripts/validate_documentation.py (depth 5)

Low Priority (Type Hints)

• Add type annotations to scripts/cli_documentation/ subpackage
• Add type annotations to scripts/extract_help.py
• Consider extending Pyright strict scope from src/ to scripts/

---

Module Quality Scorecard

Module	Avg Complexity	MI Score	Smells	Grade
src/azlin/__init__.py	A	100.00	0	A+
scripts/cli_documentation/validator.py	A	73.56	0	A
scripts/cli_documentation/hasher.py	A	69.92	0	A
scripts/cli_documentation/models.py	A	66.37	0	A
scripts/cli_documentation/sync_manager.py	A	67.40	1	A-
src/azlin/rust_bridge.py	C (15 peak)	49.84	1	B
scripts/audit_key_operations.py	C (12 peak)	62.22	1	B
scripts/doc_sync.py	E (38 peak)	62.69	3	D
scripts/validate_documentation.py	C (15 peak)	42.77	2	C
scripts/extract_help.py	C (13 peak)	43.41	1	C
scripts/generate_docs.py	B peak	49.36	3	C

---

Baseline Metrics (2026-03-23)

{
  "date": "2026-03-23",
  "overall_score": 74,
  "loc_total": 4704,
  "lloc": 1912,
  "avg_complexity": 4.09,
  "docstring_coverage_pct": 92,
  "return_type_coverage_pct": 67,
  "todo_count": 0,
  "long_functions": 18,
  "critical_complexity_functions": 1,
  "deep_nesting_files": 6,
  "modules": {
    "src/azlin/__init__.py":             {"mi": 100.00, "grade": "A+"},
    "src/azlin/rust_bridge.py":          {"mi": 49.84,  "grade": "B"},
    "scripts/doc_sync.py":               {"mi": 62.69,  "grade": "D", "critical": true},
    "scripts/validate_documentation.py": {"mi": 42.77,  "grade": "C"},
    "scripts/extract_help.py":           {"mi": 43.41,  "grade": "C"},
    "scripts/generate_docs.py":          {"mi": 49.36,  "grade": "C"},
    "scripts/audit_key_operations.py":   {"mi": 62.22,  "grade": "B"},
    "scripts/cli_documentation/extractor.py":    {"mi": 60.05, "grade": "B"},
    "scripts/cli_documentation/sync_manager.py": {"mi": 67.40, "grade": "A-"},
    "scripts/cli_documentation/example_manager.py": {"mi": 67.74, "grade": "A-"},
    "scripts/cli_documentation/hasher.py":       {"mi": 69.92, "grade": "A"},
    "scripts/cli_documentation/models.py":       {"mi": 66.37, "grade": "A"},
    "scripts/cli_documentation/generator.py":    {"mi": 63.16, "grade": "A-"},
    "scripts/cli_documentation/validator.py":    {"mi": 73.56, "grade": "A"}
  }
}

---

This issue tracks the baseline established 2026-03-23. Future monthly reports will measure progress against these numbers.

Generated by Code Quality Tracker