🩺 CodeSurgeon

AI-Powered Architecture Governance System

Built with GitHub Copilot CLI

---

🚀 Overview

CodeSurgeon is a terminal-native architecture governance engine that analyzes Python codebases, evaluates architectural health, and enforces quality thresholds in CI/CD pipelines.

Built collaboratively using GitHub Copilot CLI, CodeSurgeon demonstrates how AI can assist not just with code generation, but with:

• System design
• Static analysis implementation
• Iterative refactoring
• Feature evolution
• CI integration
• Developer workflow automation

It transforms architecture quality into a measurable, enforceable metric.

---

🎯 Why CodeSurgeon?

Modern teams often detect architectural issues too late:

• Large monolithic files
• High cyclomatic complexity
• Circular dependencies
• Duplicate logic
• Gradual architecture degradation

CodeSurgeon solves this by:

✔ Scanning project structure
✔ Measuring complexity
✔ Detecting circular dependencies
✔ Identifying duplicate implementations
✔ Calculating an architecture health score
✔ Generating actionable recommendations
✔ Failing CI builds when thresholds are not met

---

🧠 Architecture Health Scoring

CodeSurgeon computes a Health Score (0–100) based on:

Issue	Penalty
Circular dependency	-5
Large file (>600 LOC)	-3
Duplicate group	-2
Function complexity > 10	-1

Risk levels:

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

This allows architecture quality to be measured objectively.

---

🔎 Features

1️⃣ Project Scanner

• Counts total lines of code
• Identifies large files (>600 LOC)

2️⃣ Dependency Analyzer

• Parses imports using ast
• Builds dependency graph
• Detects circular dependencies via DFS

3️⃣ Duplicate Detector

• Extracts functions using ast
• Normalizes function bodies
• Uses hashing to detect identical implementations

4️⃣ Complexity Metrics

• Computes cyclomatic complexity
• Identifies high-complexity functions
• Reports average, min, max complexity

5️⃣ Recommendation Engine

Generates structured, actionable insights:

• Refactoring suggestions
• Module extraction guidance
• Circular dependency fixes
• Duplicate consolidation advice

6️⃣ JSON Export Mode

python main.py . --all --json

Outputs complete structured analysis for automation tools.

7️⃣ CI/CD Integration Mode

python main.py . --ci --threshold 85

• Exits with code 0 if health ≥ threshold
• Exits with code 1 if health < threshold
• Can be used in GitHub Actions, Jenkins, etc.

This enables automated architecture governance in pull requests.

---

🛠 Usage

Full Analysis

python main.py . --all

Individual Analyses

--scan              # Project structure and LOC
--dependencies      # Dependency graph and circular deps
--duplicates        # Duplicate function detection
--metrics           # Complexity metrics
--score             # Health score calculation
--recommendations   # Actionable improvement suggestions

JSON Output

python main.py . --all --json

CI Mode

python main.py . --ci --threshold 80

---

🧪 Example CI Usage (GitHub Actions)

- name: Run CodeSurgeon
  run: python main.py . --ci --threshold 85

If architecture health drops below 85, the pipeline fails.

---

🤖 Built with GitHub Copilot CLI

CodeSurgeon was developed entirely in the terminal using GitHub Copilot CLI.

Copilot was used to:

• Generate module scaffolding
• Implement AST-based parsing logic
• Refactor architecture
• Add structured JSON output
• Implement CI exit codes
• Improve terminal formatting
• Test edge cases
• Validate output correctness

Rather than simply generating code, Copilot acted as a collaborative AI development partner throughout the design and iteration process.

---

🏗 Technical Highlights

• Uses only Python built-in libraries
• Modular architecture
• Clean CLI interface
• Structured data output
• CI-ready enforcement logic
• Terminal-friendly formatting

---

🌟 Vision

CodeSurgeon demonstrates how AI-assisted development tools like GitHub Copilot CLI can help engineers:

• Architect systems
• Enforce quality standards
• Build automation-ready tools
• Integrate governance into CI pipelines

It moves Copilot from "code autocomplete" to "architecture co-pilot."

---

📌 Future Extensions

• Language support expansion
• Trend tracking across commits
• Pull request diff analysis
• Visualization dashboard

---

🎯 Built for the GitHub Copilot CLI Challenge 2026