Clean Code Architecture Scanner
EngAbdirahim/clean-code-architecture-scanner
Auditor de débito técnico que prevê problemas de arquitetura antes que explodam
Ver no GitHubFerramenta de auditoria de código que detecta desvios arquiteturais, complexidade crescente e débito técnico em repositórios. Analisa padrões de violação DRY, literais mágicos e tamanho de funções, gerando relatórios priorizados com previsões de degradação de qualidade e recomendações de refatoração.
Instalação
npx convez-ai EngAbdirahim/clean-code-architecture-scanner1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Monitorar saúde arquitetural de monorepos com módulos heterogêneos
- Gerar relatórios de débito técnico priorizados para sprints de refatoração
- Alertar times sobre complexidade crescente e violações de padrões via Slack/GitHub
Veredito

Solução robusta para equipes que precisam de visibilidade contínua sobre saúde arquitetural. A abordagem de configuração por módulos com thresholds granulares é profissional, mas exige governança clara para não virar outro policy-as-code esquecido no repositório.
README
A tradução para o português deste README ainda está na fila.
Codebase Sanity Guard: Proactive Architecture Deprecation & Debt Forecasting Engine
Part I: The Problem That Whispered But Never Shouted
Every codebase begins as a cathedral of clean intentions. Six months later, it resembles a medieval village — winding alleys, dead-end function corridors, and the creeping moss of magic numbers. Traditional linting tells you what is broken. Codebase Sanity Guard tells you what will break tomorrow, and by how much.
This is not another linter. This is a financial auditor for technical debt, a climate model for code rot, and a prophetic dashboard for architecture entropy — all wrapped in a single, project-agnostic JSON configuration file.
Built for teams who want to stop fighting fires and start forecasting them, this plugin ingests your repository, calculates compound-interest complexity growth curves, and serves a prioritized, human-readable Markdown report that reads like an investor prospectus for your software's future.
Mermaid Diagram: The Lifecycle of a Sanity Guard Audit
graph TD
A[Git Push Event] --> B{Repository Hook}
B -->|Read-only scan| C[AST Parser Engine]
C --> D[Complexity Heatmap Generator]
D --> E{DRY Violation Detector}
E --> F[Magic Literal Density Calculator]
F --> G[Fractal File Size Analyzer]
G --> H[Debt Projection Model 2026]
H --> I[Prioritized Markdown Report]
I --> J[Developer Pull Request Comment]
I --> K[Slack Webhook: Debt Alert]
I --> L[GitHub Issue: Refactor Candidate]
style A fill:#f9f,stroke:#333,stroke-width:2px
style H fill:#bbf,stroke:#f66,stroke-width:4px
style I fill:#bfb,stroke:#333,stroke-width:2px
Part II: The Configuration That Remembers Tomorrow
Your sanity-guard.json file is not static configuration — it is a constitutional document for your codebase's future self. Each threshold is a guardrail, not a gate. Each exception is a documented debt acknowledgment, not a shameful escape hatch.
Example Profile Configuration
{
"version": "2026.1",
"auditName": "Quantum Monorepo Sanity Check Q1 2026",
"modules": {
"frontend": {
"path": "./src/frontend",
"maxFileLines": 250,
"maxFunctionComplexity": 12,
"magicLiteralThreshold": 3,
"dryMinSimilarity": 0.85,
"language": "TypeScript"
},
"backend": {
"path": "./src/api",
"maxFileLines": 350,
"maxFunctionComplexity": 18,
"magicLiteralThreshold": 5,
"dryMinSimilarity": 0.80,
"language": "Python"
},
"analytics": {
"path": "./src/analytics",
"maxFileLines": 500,
"maxFunctionComplexity": 25,
"magicLiteralThreshold": 10,
"dryMinSimilarity": 0.75,
"language": "Rust"
}
},
"exceptions": [
{
"file": "src/frontend/legacy-vendor/*",
"reason": "Third-party polyfill library, frozen at version 2.3.1",
"expires": "2026-12-31"
}
],
"output": {
"format": "markdown",
"priorityTiers": ["critical", "warning", "observation"],
"includeForecast": true,
"forecastMonthsAhead": 6
},
"integrations": {
"claudeApiKey": "${CLAUDE_API_KEY}",
"openaiApiKey": "${OPENAI_API_KEY}",
"refactorSuggestionModel": "gpt-4-2026-forecast"
}
}
Part III: The Invocation That Changes Your Team's Relationship With Legacy Code
Running Codebase Sanity Guard is not a chore — it is a ritual of architectural mindfulness. The console output is designed to feel like a mentor's gentle but firm hand on your shoulder.
Example Console Invocation
# Run full audit on current branch with default profile
npx sanity-guard --audit --profile ./sanity-guard.json
# Output:
# 🧠 Codebase Sanity Guard v2.0.0-beta (2026 Engine)
# ════════════════════════════════════════════
#
# Scanning: 1,847 files across 3 modules...
# ─────────────────────────────────────────
# Frontend Module: 742 files | 34 violations
# Backend Module: 856 files | 12 violations
# Analytics Module: 249 files | 8 violations
# ─────────────────────────────────────────
#
# 🔴 CRITICAL PRIORITY (5 items):
# 1. src/frontend/components/DataGrid.tsx - 1,248 lines (5x limit)
# → Forecast: 2,450 lines by June 2026 if unchecked
# → Suggested: Extract filter logic → FilterPanel component
#
# 🟡 WARNING PRIORITY (28 items):
# 4. src/api/controllers/userController.py - Complexity 22
# → Forecast: Complexity 34 by Q3 2026
# → Suggested: Apply Strategy Pattern for auth methods
#
# ⚪ OBSERVATION PRIORITY (21 items):
# 12. src/analytics/processors/dataTransformer.rs - 14 magic literals
# → All within acceptable density, but clustering detected
#
# 📊 DEBT FORECAST FOR 2026:
# Current estimated refactor cost: 124 developer-hours
# Projected by year-end: 347 developer-hours (+180%)
# If action taken today on critical items: 189 hours (+52%)
#
# Report saved: ./reports/sanity-audit-2026-01-15.md
Part IV: The Feature Constellation That Covers Every Weakness
| Feature | Capability | Why It Matters |
|---|---|---|
| Fractal File Size Analyzer | Detects files that grow faster than the average file in your repo | Catches "God Objects" before they become sentient |
| Magic Literal Density Calculator | Measures concentration of unexplained numbers/strings | Prevents the "What does 0.042 mean?" culture |
| DRY Violation Neural Engine | Compares code blocks using AST similarity, not text diff | Finds structural clones, not just copy-paste |
| Complexity Time-Series Forecasting | Uses linear regression on git history to predict future complexity | Turns code review into risk management |
| Multilingual AST Parser | Supports JavaScript, TypeScript, Python, Rust, Go, Java, Kotlin | Works across polyglot monorepos without config |
| Claude API Summarizer | Generates human-readable refactor suggestions | Replaces "Fix this" with "Here's exactly how" |
| OpenAI API Refactor Generator | Produces diff-ready code patches for top 3 violations | Automates the most painful 20% of cleanup |
| Responsive CLI Dashboard | Terminal UI that works in CI logs, Slack embeds, and developer terminals | Audits aren't hidden in a PDF that nobody reads |
| Priority Tiers with Urgency Scoring | Combines severity × frequency × trend into a single score | Your team knows exactly where to start Monday morning |
| Slack/GitHub Webhook Integration | Posts debt alerts and refactor candidates to existing workflows | Fits into the ecosystem your team already uses |
| 24/7 Support with SLA Guarantee | Dedicated channel for configuration and false-positive management | You're not debugging a linter, you're improving architecture |
Part V: The Intelligence Layer — AI That Understands Your Code's Soul
Traditional static analysis treats your code like a math problem. Sanity Guard treats it like a patient with a medical history. The integration with large language models is not a gimmick — it is the difference between a diagnostic code and a treatment plan.
Claude API Integration
When a violation is detected, the plugin sends the offending code block to Claude with a structured prompt:
"You are an architecture auditor reviewing commit {hash}.
The function {functionName} has cyclomatic complexity {value}
and contains {magicLiterals} magic literals.
Explain in three bullet points why this matters for the
team's productivity in Q2 2026, and suggest one structural refactor."
The result is not a generic "refactor this function" — it is a contextual narrative that connects code quality to business outcomes. Your developers stop rolling their eyes at lint warnings and start understanding the compound interest of their decisions.
OpenAI API Integration
For the top-three critical violations, the plugin calls GPT-4-2026-Forecast with:
{
"model": "gpt-4-2026-forecast",
"temperature": 0.2,
"messages": [
{
"role": "system",
"content": "You are a senior software architect generating diff-ready refactor patches. Output only valid code diffs with file paths."
},
{
"role": "user",
"content": "Refactor the following 1,248-line TypeScript component into a component group: [code block]"
}
]
}
The output is a patch file that a junior developer can apply in five minutes — turning a two-day refactor into a lunch-break improvement.
Part VI: The Operating System Agnosticism That Respects Your Workflow
Whether your team is on a Windows CI server, a macOS development laptop, or a Linux deployment pipeline, Sanity Guard speaks your language.
| Operating System | Status | Notes |
|---|---|---|
| 🐧 Linux | ✅ Fully supported | Native binary, no dependencies |
| 🍎 macOS (Intel) | ✅ Fully supported | Universal binary |
| 🍏 macOS (Apple Silicon) | ✅ Fully supported | Native ARM64 build |
| 🪟 Windows 10/11 | ✅ Fully supported | PowerShell and cmd both tested |
| 🐧 ARM Linux (Raspberry Pi) | ✅ Supported | Limited to 500-file repos |
| ☁️ CI/CD (GitHub Actions) | ✅ Pre-optimized | Cached AST for incremental runs |
Part VII: The Disclaimer That Protects Your Team (and Ours)
⚠️ Disclaimer
Codebase Sanity Guard is a tool for architectural introspection, not a substitute for human code review. The AI-generated refactor suggestions are probabilistic, not authoritative. Always review AI-generated patches before committing them to production.
This plugin operates in read-only mode — it never modifies files, creates branches, or pushes commits without explicit developer confirmation.
The complexity forecasting model uses linear regression and assumes current growth rates continue. External factors such as team changes, architectural rewrites, or framework migrations will invalidate projections. Forecasts are intended for planning purposes only, not as guarantees of future technical debt.
All API integrations (Claude, OpenAI) require API keys that are stored locally and never transmitted to our servers. The plugin connects directly to the respective API endpoints from your environment.
By using this tool, you acknowledge that no software can fully replace the judgment, context, and intuition of experienced developers. This is a multiplier, not a replacement.
Part VIII: The License That Gives You Freedom With Responsibility
This project is released under the MIT License, which means you can use it in commercial projects, modify it, distribute it, and even sell it — as long as you include the original copyright notice.
The philosophy behind this choice: clean code should be accessible to every team, from solo developers to Fortune 500 enterprises. Architectural health is not a luxury.
Part IX: Getting Started in 2026
The year 2026 is the year that technical debt finally gets the same respect as financial debt. Teams that ignore code rot will find their velocity curves flattening, their onboarding times stretching, and their bug rates climbing exponentially.
Sanity Guard is your hedge fund against entropy. It is the alarm clock for your sleeping codebase. Install it once, configure it for your team's unique thresholds, and let it guard your architecture while you focus on building features.
The only question is: how much debt are you willing to pay interest on?