convez.ai
SkillDevOps & InfraestruturaAvançado
EngAbdirahim

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 GitHub
InicialPluginScore · de 0 a 100

Ferramenta 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-scanner

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

Download Version License

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

FeatureCapabilityWhy It Matters
Fractal File Size AnalyzerDetects files that grow faster than the average file in your repoCatches "God Objects" before they become sentient
Magic Literal Density CalculatorMeasures concentration of unexplained numbers/stringsPrevents the "What does 0.042 mean?" culture
DRY Violation Neural EngineCompares code blocks using AST similarity, not text diffFinds structural clones, not just copy-paste
Complexity Time-Series ForecastingUses linear regression on git history to predict future complexityTurns code review into risk management
Multilingual AST ParserSupports JavaScript, TypeScript, Python, Rust, Go, Java, KotlinWorks across polyglot monorepos without config
Claude API SummarizerGenerates human-readable refactor suggestionsReplaces "Fix this" with "Here's exactly how"
OpenAI API Refactor GeneratorProduces diff-ready code patches for top 3 violationsAutomates the most painful 20% of cleanup
Responsive CLI DashboardTerminal UI that works in CI logs, Slack embeds, and developer terminalsAudits aren't hidden in a PDF that nobody reads
Priority Tiers with Urgency ScoringCombines severity × frequency × trend into a single scoreYour team knows exactly where to start Monday morning
Slack/GitHub Webhook IntegrationPosts debt alerts and refactor candidates to existing workflowsFits into the ecosystem your team already uses
24/7 Support with SLA GuaranteeDedicated channel for configuration and false-positive managementYou'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 SystemStatusNotes
🐧 Linux✅ Fully supportedNative binary, no dependencies
🍎 macOS (Intel)✅ Fully supportedUniversal binary
🍏 macOS (Apple Silicon)✅ Fully supportedNative ARM64 build
🪟 Windows 10/11✅ Fully supportedPowerShell and cmd both tested
🐧 ARM Linux (Raspberry Pi)✅ SupportedLimited to 500-file repos
☁️ CI/CD (GitHub Actions)✅ Pre-optimizedCached 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.

Read the full MIT License


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?

Download Stars Issues

Ver o original no GitHub

Bom para

Relacionados