I Built a Python CLI That Scores Your Codebase Health (and Fails Your CI If It's Bad)

Amit Tiwari — Sun, 15 Feb 2026 21:19:01 +0000

🧠 CodeSurgeon – A CLI Tool That Analyzes Your Python Architecture & Fails Your CI If It’s Unhealthy

This is a submission for the GitHub Copilot CLI Challenge.

🚀 What I Built

I built CodeSurgeon — a Python CLI tool that performs deep architectural analysis of Python projects and generates:

📊 Cyclomatic complexity metrics
🔁 Circular dependency detection
♻️ Duplicate function detection
📁 Large file detection
🧠 Architecture health score (0–100)
🚨 CI mode that fails pipelines when quality drops
📦 Full structured JSON output

Built using only Python standard libraries (ast, os, hashlib, json, etc.).

🎯 Why CodeSurgeon?

Most static analysis tools:

Require heavy dependencies
Focus only on linting
Don’t give architecture health scoring
Don’t integrate cleanly into CI

CodeSurgeon acts like a doctor for your codebase:

It scans.

It diagnoses.

It scores.

It recommends.

It enforces quality in CI.

🧪 Demo

🎥 Video Walkthrough

https://youtu.be/SHOAeKBbcPU

In the demo, I show:

Running full analysis
Generating formatted terminal output
Producing JSON output
Running CI mode
Triggering a CI failure

📦 GitHub Repository

👉 https://github.com/codyamit/codesurgeon

🔎 Core Features

1️⃣ Scanner Engine

Counts total lines of code
Detects files > 600 LOC
Structured results

2️⃣ Dependency Analyzer

Parses Python files using ast
Extracts import statements
Builds dependency graph
Detects circular dependencies using DFS

3️⃣ Duplicate Function Detector

Extracts functions via AST
Normalizes bodies
Hashes with hashlib.md5
Groups identical implementations

4️⃣ Metrics Calculator

Cyclomatic Complexity:

Complexity = 1 + number_of_branching_nodes

Branching nodes counted:

if
for
while
try
with
boolean operators (and/or)

Tracks:

total functions
average complexity
max complexity
functions over threshold

🧠 Architecture Health Score

Scoring:

Start at 100
−5 per circular dependency
−3 per large file (>600 LOC)
−2 per duplicate group
−1 per high-complexity function (>10)
Clamped 0–100

Risk Levels:

80–100 → Low
60–79 → Moderate
40–59 → High
0–39 → Critical

📦 JSON Output Mode

python3 main.py . --json

Outputs structured JSON:

{
  "path": ".",
  "scanner": {...},
  "dependencies": {...},
  "metrics": {...},
  "duplicates": {...},
  "health_score": {...},
  "recommendations": {...}
}

Perfect for dashboards and automation.

🚨 CI/CD Mode

python3 main.py . --ci --threshold 85

Behavior:

Runs full analysis
Compares score with threshold
Exit code 0 → PASS
Exit code 1 → FAIL

Example:

Health Score: 91
CI Threshold: 95
FAILED
Exit code: 1

Pipeline-ready.

🛠 CLI Usage

python3 main.py . --all
python3 main.py . --scan
python3 main.py . --metrics
python3 main.py . --json
python3 main.py . --ci --threshold 90

💻 My Experience Using GitHub Copilot CLI

This entire project was built with GitHub Copilot CLI.

Copilot helped me:

Generate project structure
Implement AST parsing logic
Write DFS cycle detection
Refactor scoring logic
Improve CLI formatting
Implement CI mode
Optimize structured JSON output

The biggest advantage?

I focused on architecture and product thinking while Copilot handled structure and boilerplate.

It genuinely felt like pair programming inside the terminal.

🧠 What I Learned

AST is extremely powerful
You can build serious tools using only standard library
Architecture scoring can be automated
CLI tools are still highly relevant
Copilot CLI accelerates system-level development dramatically

🔥 Why This Is Different

This isn’t just:

A linter
A metrics tool
A dependency analyzer

It’s a unified architecture health platform for Python projects.

Works in:

Local development
CI/CD pipelines
JSON automation workflows

🚀 Future Improvements

Multi-language support
Graph visualization export
HTML reports
GitHub Action template
Trend tracking
PR comment integration

🎯 Final Thoughts

CodeSurgeon was built from scratch in one focused sprint using GitHub Copilot CLI.

And honestly?

This is one of the cleanest CLI tools I’ve ever built.

If you like the idea, give it a ⭐ on GitHub: