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

🧠 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:

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