Skip to content
/ GoClean Public

A simple utility for scanning a Go codebase and identify potential clean code issues.

License

MIT license
0 stars 0 forks Branches Tags Activity
Star

ericfisherdev/GoClean

BranchesTags

Repository files navigation

GoClean

A powerful multi-language CLI tool that scans codebases to identify clean code violations with real-time HTML reporting and AI-friendly markdown output. Now with initial Rust support! (regex-based parsing with planned syn crate integration)

Go Version Rust Support License Build Status Release Performance

Features

🔍 Multi-Language Analysis

  • Go: Complete support with AST-based analysis
  • Rust: Full language support with ownership analysis, error handling patterns, and clippy integration
  • Additional Languages: JavaScript, TypeScript, Python, Java, C# (planned)

📊 Comprehensive Code Quality Checks

  • Function Quality: Detect long functions, high complexity, excessive parameters
  • Naming Conventions: Language-specific naming pattern validation
  • Code Structure: Find large classes, deep nesting, and code duplication
  • Documentation: Track missing docs, outdated comments, and technical debt
  • Rust-Specific: Ownership patterns, error handling, unsafe code analysis

🚀 Rich Reporting & Integration

  • 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
  • CI/CD Ready: Exit codes, JSON output, and performance metrics
  • Clippy Integration: Leverage rust-clippy's 790+ lints alongside GoClean analysis

⚙️ Highly Configurable

  • Language-Specific Rules: Tailored thresholds and checks per language
  • Custom Thresholds: Adjust limits for functions, complexity, naming rules
  • Flexible Output: Choose report formats and customize styling
  • Team Standards: Version-controlled configuration for consistent rules

Installation

Pre-built Binaries (Recommended)

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"

# Verify installation with Rust support
goclean version

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

Build Configuration

The build system supports configurable paths for enhanced Rust support:

# Default: uses ./rust/parser relative to project root
make build

# Override Rust parser path via environment variable
RUST_PARSER_PATH=/path/to/rust-parser make build

# Override via command line
make build RUST_PARSER_PATH=/custom/path

Quick Start

Go Projects

# Scan current directory with defaults
goclean scan

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

# Generate configuration file
goclean config init

Rust Projects

# Scan Rust project with ownership analysis
goclean scan --languages rust

# Initialize Rust-specific configuration
goclean config init --template rust

# Scan with clippy integration
goclean scan --languages rust --enable-clippy

Mixed Go/Rust Projects

# Scan both languages
goclean scan --languages go,rust

# Use mixed project configuration
goclean scan --config configs/rust-mixed-project.yaml

Rust Support

GoClean provides comprehensive Rust analysis with 15 specialized detectors:

Core Rust Detectors

  • RustFunctionDetector: Function complexity, length, parameters
  • RustNamingDetector: snake_case, PascalCase, SCREAMING_SNAKE_CASE conventions
  • RustDocumentationDetector: Missing documentation on public items
  • RustMagicNumberDetector: Magic numbers and constants
  • RustDuplicationDetector: Code duplication analysis
  • RustStructureDetector: Module and file organization

Advanced Rust Analysis

  • RustOwnershipDetector: Ownership and borrowing pattern analysis
  • RustErrorHandlingDetector: Result/Option usage and error propagation
  • RustTraitDetector: Trait design and implementation issues
  • RustUnsafeDetector: Unsafe code block analysis
  • RustPerformanceDetector: Performance anti-patterns

Clippy Integration

  • 790+ Additional Lints: Leverages rust-clippy's comprehensive lint collection
  • 5 Core Categories: correctness, suspicious, style, complexity, performance
  • Seamless Integration: Clippy violations appear alongside GoClean analysis
  • Proper Attribution: All clippy violations clearly marked "Detected by rust-clippy"

Rust-Specific Violation Types

Naming Violations:
- RUST_INVALID_FUNCTION_NAMING
- RUST_INVALID_STRUCT_NAMING  
- RUST_INVALID_ENUM_NAMING
- RUST_INVALID_TRAIT_NAMING
- RUST_INVALID_CONSTANT_NAMING
- RUST_INVALID_MODULE_NAMING
- RUST_INVALID_VARIABLE_NAMING

Documentation Violations:
- RUST_MISSING_DOCUMENTATION

Ownership Violations:
- RUST_UNNECESSARY_CLONE
- RUST_INEFFICIENT_BORROWING
- RUST_COMPLEX_LIFETIME
- RUST_MOVE_SEMANTICS_VIOLATION
- RUST_BORROW_CHECKER_BYPASS

Error Handling:
- RUST_OVERUSE_UNWRAP
- RUST_MISSING_ERROR_PROPAGATION
- RUST_INCONSISTENT_ERROR_TYPE
- RUST_PANIC_PRONE_CODE
- RUST_UNHANDLED_RESULT
- RUST_IMPROPER_EXPECT

Safety Violations:
- RUST_UNNECESSARY_UNSAFE
- RUST_UNSAFE_WITHOUT_COMMENT
- RUST_TRANSMUTE_ABUSE
- RUST_RAW_POINTER_ABUSE

Performance Violations:
- RUST_INEFFICIENT_STRING_CONCAT
- RUST_UNNECESSARY_ALLOCATION
- RUST_BLOCKING_IN_ASYNC
- RUST_INEFFICIENT_ITERATION
- RUST_UNNECESSARY_COLLECTION

Pattern Matching:
- RUST_NON_EXHAUSTIVE_MATCH
- RUST_NESTED_PATTERN_MATCHING
- RUST_INEFFICIENT_DESTRUCTURING
- RUST_UNREACHABLE_PATTERN
- RUST_MISSING_MATCH_ARM

Trait Violations:
- RUST_OVERLY_COMPLEX_TRAIT
- RUST_MISSING_TRAIT_IMPL
- RUST_TRAIT_BOUND_COMPLEXITY
- RUST_ORPHAN_RULE

Module Violations:
- RUST_IMPROPER_VISIBILITY
- RUST_CIRCULAR_DEPENDENCY
- RUST_MODULE_ORGANIZATION
- RUST_UNUSED_IMPORT

Configuration Examples

Basic Rust Configuration

# goclean.yaml
scan:
  paths: ["./src"]
  languages: ["rust"]
  exclude: ["target/", "Cargo.lock"]

rust:
  enable_ownership_analysis: true
  enable_error_handling_check: true
  enable_pattern_match_check: true
  max_lifetime_params: 3
  enforce_result_propagation: true

clippy:
  enabled: true
  lint_groups: ["correctness", "suspicious", "style"]

thresholds:
  function_lines: 30
  cyclomatic_complexity: 10
  parameters: 4

Mixed Go/Rust Project

# goclean.yaml
scan:
  paths: ["./src", "./rust-modules"]
  languages: ["go", "rust"]
  exclude: ["vendor/", "target/"]

# Language-specific thresholds
thresholds:
  go:
    function_lines: 25
    parameters: 3
    cyclomatic_complexity: 8
  rust:
    function_lines: 30
    parameters: 4
    cyclomatic_complexity: 10

rust:
  enable_ownership_analysis: true
  enable_error_handling_check: true
  clippy_integration:
    enabled: true
    lint_groups: ["correctness", "suspicious", "style", "complexity", "perf"]

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

Enterprise Rust Configuration

# configs/rust-strict.yaml - Production-ready strict standards
rust:
  enable_ownership_analysis: true
  enable_error_handling_check: true
  enable_pattern_match_check: true
  allowed_unsafe_patterns: []  # No unsafe code allowed
  max_lifetime_params: 2
  max_trait_bounds: 3
  enforce_result_propagation: true

clippy:
  enabled: true
  lint_groups: ["correctness", "suspicious", "style", "complexity", "perf"]
  fail_on_clippy_errors: true

thresholds:
  function_lines: 20
  cyclomatic_complexity: 6
  parameters: 3

Performance

GoClean delivers exceptional performance for both Go and Rust analysis:

Metric Go Analysis Rust Analysis Status
Scanning Speed 8,678 files/sec 6,200 files/sec ✅ Excellent
Memory Usage ~27MB per 1k files ~35MB per 1k files ✅ Efficient
Parse Accuracy 100% (go/ast) 100% (syn crate) ✅ Perfect
Clippy Integration N/A ~500ms overhead ✅ Fast

Rust Parser Technology: Uses the industry-standard syn crate via CGO for 100% accuracy and complete Rust language support.

Advanced Usage

CLI Examples

# Language-specific analysis
goclean scan --languages rust --console-violations
goclean scan --languages go --html

# Rust-specific features
goclean scan --languages rust --rust-features ownership,error-handling
goclean scan --languages rust --enable-clippy --clippy-categories correctness,suspicious

# Mixed project with custom config
goclean scan --config configs/rust-mixed-project.yaml --html --markdown

# CI/CD integration
goclean scan --languages go,rust --format json --quiet --severity high

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)
    }
    
    // Enable Rust analysis
    cfg.Languages = []string{"go", "rust"}
    cfg.Rust.EnableOwnershipAnalysis = true
    
    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)
    
    // Language-specific statistics
    goViolations := result.GetViolationsByLanguage("go")
    rustViolations := result.GetViolationsByLanguage("rust")
    
    fmt.Printf("Go: %d violations, Rust: %d violations\n", 
        len(goViolations), len(rustViolations))
}

Architecture

GoClean/
├── cmd/goclean/          # CLI entry point with multi-language support
├── internal/             # Core application logic
│   ├── config/           # Multi-language configuration management
│   ├── scanner/          # Go and Rust parsing engines
│   │   ├── rust_*.go     # Rust-specific analyzers and parsers
│   │   └── go_*.go       # Go-specific analyzers
│   ├── violations/       # Language-specific violation detectors
│   │   ├── rust_*.go     # 15 Rust detectors + clippy integration
│   │   └── go_*.go       # Go violation detectors
│   ├── reporters/        # Multi-language report generation
│   └── models/           # Data structures for both languages
├── lib/                  # Rust parser library (CGO integration)
├── configs/              # Language-specific configuration templates
│   ├── rust-*.yaml       # Rust configuration examples
│   └── mixed-*.yaml      # Multi-language project configs
└── docs/                 # Comprehensive documentation
    ├── rust-*.md          # Rust-specific documentation
    └── *.md               # General documentation

Use Cases

Development Teams

  • Go Teams: Maintain clean Go codebases with established patterns
  • Rust Teams: Enforce memory safety and idiomatic Rust practices
  • Mixed Teams: Consistent quality standards across Go and Rust code
  • Legacy Migration: Track quality during Go-to-Rust transitions

CI/CD Integration

  • Quality Gates: Fail builds on critical violations
  • Code Reviews: Automated analysis before merging
  • Technical Debt: Track improvements over time
  • Performance Monitoring: Detect performance anti-patterns

Enterprise Usage

  • Code Standards: Enforce company-wide coding standards
  • Training: Help developers learn clean code principles
  • Auditing: Comprehensive codebase quality assessment
  • Refactoring: Identify improvement opportunities

Documentation

Comprehensive documentation is available in the docs/ directory:

Document Description
📖 User Guide Installation, configuration, and usage guide
🦀 Rust Integration Examples Complete Rust analysis setup and usage
⚙️ Configuration Reference Detailed configuration options
🛠️ Developer Guide Contributing guidelines and architecture
📚 API Reference Programmatic API documentation

Rust-Specific Documentation

Contributing

We welcome contributions for both Go and Rust features! Please see our Developer Guide for:

  • Development setup and workflow
  • Adding new language support or detectors
  • Testing strategies for multi-language projects
  • Architecture overview and coding 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 (includes Rust parser)
go mod download
make build
make test

# Test both Go and Rust analysis
make test

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

# Submit pull request

Support

License

MIT License - see LICENSE file for details.

GoClean: Clean code analysis for the modern polyglot world

Made with ❤️ by Eric Fisher

Supporting Go since 2024, Rust since 2025

About

A simple utility for scanning a Go codebase and identify potential clean code issues.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

GoClean 2025.08.16.13 Latest
Aug 16, 2025
+ 1 release

Packages

No packages published

Contributors 2

  •  
  •  

Languages