goclean

README

GoClean

A powerful Go CLI tool that scans codebases to identify clean code violations with real-time HTML reporting and AI-friendly markdown output.

Features

🔍 Comprehensive Analysis

• Function Quality: Detect long functions, high complexity, excessive parameters
• Naming Conventions: Identify non-descriptive names and inconsistent patterns
• Code Structure: Find large classes, deep nesting, and code duplication
• Documentation: Track missing docs, outdated comments, and technical debt

📊 Rich Reporting

• Interactive HTML Dashboard: Real-time auto-refreshing reports with modern UI
• AI-Friendly Markdown: Structured output optimized for AI analysis tools
• Multiple Formats: Console tables, JSON, CSV exports
• Detailed Insights: Code snippets, severity indicators, improvement suggestions

⚙️ Highly Configurable

• Custom Thresholds: Adjust limits for functions, complexity, naming rules
• Language Support: Go, JavaScript, TypeScript, Python, Java, C#
• Flexible Output: Choose report formats and customize styling
• Team Standards: Version-controlled configuration for consistent rules

Installation

Pre-built Binaries

Download from GitHub Releases:

# Linux/macOS
curl -L https://github.com/ericfisherdev/goclean/releases/latest/download/goclean-linux-amd64 -o goclean
chmod +x goclean && sudo mv goclean /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/ericfisherdev/goclean/releases/latest/download/goclean-windows-amd64.exe" -OutFile "goclean.exe"

Go Install

go install github.com/ericfisherdev/goclean/cmd/goclean@latest

Build from Source

git clone https://github.com/ericfisherdev/goclean.git
cd goclean && make build

Quick Start

# Scan current directory with defaults
goclean scan

# Scan specific paths
goclean scan --path ./src --path ./internal

# Generate configuration file
goclean config init

# Custom scan with configuration  
goclean scan --config ./goclean.yaml --html --markdown

# Filter by severity
goclean scan --severity high --console

# CI/CD friendly output
goclean scan --format json --no-color --quiet

Project Status

✅ Production Ready - All core features implemented and tested

Development Progress

• Phase 1: Foundation (Project structure, CLI framework, configuration)
• Phase 2: Core Detection (AST parsing, violation detection, severity classification)
• Phase 3: Reporting System (HTML templates, real-time updates, file navigation)
• Phase 4: Enhanced Features (Markdown output, advanced detection, performance optimization)
• Phase 5: Polish and Documentation (UI improvements, comprehensive docs, testing)

Documentation

Comprehensive documentation is available in the docs/ directory:

Document	Description
📖 User Guide	Complete installation, configuration, and usage guide
⚙️ Configuration Reference	Detailed configuration options and examples
🛠️ Developer Guide	Contributing guidelines and architecture overview
📚 API Reference	Programmatic API documentation for integrations

Quick Links

• Installation Instructions
• Configuration Examples
• Adding Custom Detectors
• CI/CD Integration

Architecture

GoClean/
├── cmd/goclean/          # CLI entry point
├── internal/             # Core application logic
│   ├── config/           # Configuration management
│   ├── scanner/          # File scanning engine
│   ├── violations/       # Violation detection
│   ├── reporters/        # Report generation
│   └── models/           # Data structures
├── web/                  # HTML templates and assets
├── configs/              # Default configuration
└── docs/                 # Comprehensive documentation

Examples

Basic Usage

# Initialize configuration
goclean config init

# Run analysis
goclean scan

# View HTML report
open reports/clean-code-report.html

Advanced Configuration

# goclean.yaml
scan:
  paths: ["./src", "./internal"]
  exclude: ["vendor/", "*.test.go"]

thresholds:
  function_lines: 20
  cyclomatic_complexity: 5
  parameters: 3

output:
  html:
    theme: "dark"
    auto_refresh: true
  markdown:
    enabled: true
    ai_friendly: true

Programmatic Usage

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/ericfisherdev/goclean/pkg/goclean"
    "github.com/ericfisherdev/goclean/pkg/config"
)

func main() {
    cfg, err := config.Load("goclean.yaml")
    if err != nil {
        log.Fatal("Failed to load config:", err)
    }
    
    analyzer := goclean.New(cfg)
    result, err := analyzer.Analyze(context.Background(), []string{"./src"})
    if err != nil {
        log.Fatal("Analysis failed:", err)
    }
    
    fmt.Printf("Found %d violations in %d files\n", 
        len(result.Violations), result.FilesScanned)
}

Performance

GoClean is designed for speed and efficiency, making it suitable for large codebases and CI/CD integration:

Metric	Target	Actual	Status
Scanning Speed	>1,000 files/sec	8,678 files/sec	✅ Exceeded
Memory Usage	<100MB per 10k files	~27MB per 1k files	✅ Met
HTML Report Generation	<2s for large reports	<200ms for 5k violations	✅ Exceeded
Startup Time	<500ms	<20μs	✅ Exceeded

Benchmark Environment: Intel i7-11800H, 16 cores, Linux amd64

See BENCHMARKS.md for detailed performance analysis.

Use Cases

• Code Reviews: Identify issues before merging
• CI/CD Pipelines: Enforce quality gates
• Refactoring: Find improvement opportunities
• Team Standards: Maintain consistent code quality
• Technical Debt: Track and prioritize fixes
• Learning: Understand clean code principles

Contributing

We welcome contributions! Please see our Developer Guide for:

• Development setup and workflow
• Architecture overview and coding standards
• Adding new features and detectors
• Testing strategies and requirements
• Documentation standards

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/your-username/goclean.git
cd goclean

# Set up development environment
go mod download
make build
make test

# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
make test
make lint

# Submit pull request

Support

• 📝 Documentation
• 🐛 Bug Reports
• 💬 Discussions
• 📧 Email Support

License

MIT License - see LICENSE file for details.

---

Made with ❤️ by Eric Fisher