Code Review Assistant

Status: Production Ready (v1.3)

A comprehensive CLI tool that analyzes codebases to provide actionable insights about code quality, complexity, maintainability, test coverage, and dependencies. Supports multiple programming languages with automatic language detection. Track your code quality metrics over time with historical comparison and multiple output formats.

Supported Languages

Language	Parsing	Metrics	Anti-Patterns	Coverage	Dependencies
Go	Go AST	Full	Full	Yes	Yes
Python	tree-sitter	Full	Full	No	No
JavaScript/TypeScript	tree-sitter	Full	Full	Yes (Jest/Vitest)	Yes

Features

Multi-Language Support

Automatic Detection: Detects project language from manifest files (go.mod, pyproject.toml, requirements.txt, setup.py, package.json, tsconfig.json)
Explicit Selection: Use --language flag to specify language manually
Extensible Architecture: Language provider system makes adding new languages straightforward

Code Metrics & Analysis

Lines of Code Analysis: Detailed breakdown of total, code, comment, and blank lines
Function Metrics: Count, average length, and 95th percentile tracking
Cyclomatic Complexity: Complexity calculation with configurable thresholds
Large File Detection: Identify files exceeding size thresholds
Long Function Detection: Flag functions that may need refactoring

Anti-Pattern Detection

Modular detector system identifies common code smells:

Too Many Parameters: Flags functions with excessive parameters (default: >5)
Deep Nesting: Detects excessive nesting depth (default: >4 levels)
Too Many Returns: Identifies functions with multiple return statements (default: >3)
Magic Numbers: Detects numeric literals that should be named constants
Duplicate Error Handling: Identifies repetitive error patterns (Go)

Test Coverage Integration (Go)

Automatic go test -cover execution for all packages
Coverage percentage parsing and reporting
Per-package coverage breakdown in verbose mode
Low coverage warnings with configurable thresholds
Graceful handling of packages without tests
Configurable timeout for test execution

Dependency Analysis (Go)

Import categorization (stdlib, internal, external)
Per-package dependency breakdown
Circular dependency detection using DFS algorithm
Too many imports warnings
Too many external dependencies warnings
Verbose mode shows full dependency lists

Multiple Output Formats

Console: Rich terminal output with tables and color-coded severity (default)
Markdown: GitHub-flavored Markdown with tables and collapsible sections
JSON: Structured JSON output for programmatic consumption and CI/CD integration
HTML: Interactive dashboard with charts, heatmaps, and dependency graphs
File output capability for all formats
Pretty-print option for JSON

Persistent Storage & Historical Tracking

File Storage: JSON-based storage in ~/.cra/history/ (default)
SQLite Storage: Structured database storage with efficient querying
Project isolation using path hashing
Automatic Git metadata extraction (commit hash, branch)
Configurable storage backend and path
Project-specific or global storage modes

Historical Comparison

Compare current analysis with previous reports
Metric deltas with percentage changes
Trend detection (improving/worsening/stable)
New and fixed issues tracking
Configurable stable threshold (default: 5%)
Visual indicators for trends

Flexible Configuration

YAML configuration file support
Environment variable overrides (CRA_ prefix)
CLI flag overrides
Exclude patterns with glob support
Per-project or global configuration
All thresholds and settings configurable

Installation

Install the latest stable release:

go install github.com/daniel-munoz/code-review-assistant@v1.3.2

Or build from source:

git clone https://github.com/daniel-munoz/code-review-assistant.git
cd code-review-assistant
go build -o code-review-assistant

Note: Building requires CGO for tree-sitter support. Make sure you have a C compiler available.

Quick Start

Analyze with Auto-Detection

The tool automatically detects the project language:

# Go project (detected via go.mod)
code-review-assistant analyze /path/to/go/project

# Python project (detected via requirements.txt, pyproject.toml, or setup.py)
code-review-assistant analyze /path/to/python/project

# JavaScript/TypeScript project (detected via package.json or tsconfig.json)
code-review-assistant analyze /path/to/js/project

Explicit Language Selection

# Explicitly analyze as Go
code-review-assistant analyze . --language go

# Explicitly analyze as Python
code-review-assistant analyze . --language python

# Explicitly analyze as JavaScript/TypeScript
code-review-assistant analyze . --language javascript

Output Formats

# Console output (default)
code-review-assistant analyze .

# Markdown report
code-review-assistant analyze . --format markdown --output-file report.md

# JSON for CI/CD
code-review-assistant analyze . --format json --output-file report.json

# Interactive HTML dashboard
code-review-assistant analyze . --format html --output-file dashboard.html

Historical Tracking

# Save and compare with previous analysis
code-review-assistant analyze . --save-report --compare

Language-Specific Features

Go

Full-featured analysis including:

Go AST-based parsing
Test coverage via go test -cover
Dependency analysis with circular dependency detection
Duplicate error handling detection (if err != nil patterns)

Default exclude patterns:

vendor/**
**/*_test.go
**/testdata/**
**/*.pb.go

Python

Tree-sitter based parsing with:

Function and class extraction
Method detection with class association
Docstring handling for comment counting
Comprehension complexity (list, dict, set, generator)
Match statement support (Python 3.10+)

Default exclude patterns:

**/__pycache__/**
**/venv/**
**/.venv/**
**/site-packages/**
**/test_*.py
**/*_test.py
**/conftest.py
**/tests/**

JavaScript/TypeScript

Tree-sitter based parsing with:

Function declarations, arrow functions, and methods
Class field extraction with initializers
JSX/TSX support
Test coverage via Jest or Vitest (reads coverage-summary.json)
Dependency analysis with Node.js builtin detection
Circular dependency detection

Default exclude patterns:

**/node_modules/**
**/dist/**
**/build/**
**/.next/**
**/*.test.js
**/*.test.ts
**/*.spec.js
**/*.spec.ts
**/__tests__/**
**/*.d.ts
**/*.min.js

Configuration

Create a config.yaml file in your project root or ~/.cra/config.yaml for global settings:

# Language selection (auto, go, python, javascript)
language: "auto"

analysis:
  # File patterns to exclude (merged with language defaults)
  exclude_patterns:
    - "generated/**"

  # Code quality thresholds
  large_file_threshold: 500      # Lines
  long_function_threshold: 50    # Lines
  min_comment_ratio: 0.15        # 15%
  complexity_threshold: 10       # Cyclomatic complexity

  # Anti-pattern detection
  max_parameters: 5              # Maximum function parameters
  max_nesting_depth: 4           # Maximum nesting depth
  max_return_statements: 3       # Maximum return statements per function
  detect_magic_numbers: true     # Detect numeric literals

  # Coverage and dependency settings (Go and JavaScript/TypeScript)
  enable_coverage: true          # Run test coverage analysis
  min_coverage_threshold: 50.0   # Minimum coverage percentage (0-100)
  coverage_timeout_seconds: 30   # Timeout for test execution per package
  max_imports: 10                # Maximum imports per package
  max_external_dependencies: 10  # Maximum external dependencies per package
  detect_circular_deps: true     # Detect circular dependencies
  detect_duplicate_errors: true  # Detect repetitive error handling

output:
  format: "console"              # Output format: console, markdown, json, html
  verbose: false                 # Show detailed per-file metrics
  output_file: ""                # Write to file instead of stdout
  json_pretty: true              # Pretty-print JSON output

storage:
  enabled: false                 # Enable persistent storage
  backend: "file"                # Storage backend: file or sqlite
  path: ""                       # Custom path (default: ~/.cra)
  auto_save: false               # Automatically save after analysis
  project_mode: false            # Use ./.cra instead of ~/.cra

comparison:
  enabled: false                 # Enable historical comparison
  auto_compare: false            # Auto-compare with latest report
  stable_threshold: 5.0          # % change for "stable" (default: 5.0)

CLI Reference

analyze

Analyze a codebase and generate a report.

Usage:

code-review-assistant analyze [path] [flags]

Language Flags:

--language, -l - Language to analyze: auto, go, python, javascript (default: auto)

General Flags:

--config, -c - Path to config file (default: ./config.yaml or ~/.cra/config.yaml)
--verbose, -v - Show verbose output with per-file and per-package details
--exclude - Additional exclude patterns (can be repeated)
--quiet, -q - Disable live status reporting

Analysis Thresholds:

--large-file-threshold - Override large file threshold in lines (default: 500)
--long-function-threshold - Override long function threshold in lines (default: 50)
--complexity-threshold - Override cyclomatic complexity threshold (default: 10)

Output & Storage Flags:

--format, -f - Output format: console, markdown, json, html (default: console)
--output-file, -o - Write output to file instead of stdout
--json-pretty - Pretty-print JSON output (default: true)
--save-report - Save report to storage for historical tracking
--compare - Compare with previous report from storage
--storage-backend - Storage backend: file or sqlite (default: file)
--storage-path - Custom storage path (default: ~/.cra)

Example Output

Console Output

Code Review Assistant - Analysis Report
============================================================

Project: /path/to/project
Analyzed: 2026-01-29 10:30:00

SUMMARY
------------------------------------------------------------
      METRIC          VALUE
------------------+--------------
  Total Files      42
  Total Lines      5,234
  Code Lines       3,845 (73.5%)
  Comment Lines    892 (17.0%)
  Blank Lines      497 (9.5%)
  Total Functions  156

AGGREGATE METRICS
------------------------------------------------------------
  Average Function Length       24.6 lines
  Function Length (95th %ile)   68 lines
  Comment Ratio                 17.0%
  Average Complexity            4.2
  Complexity (95th %ile)        12

ISSUES FOUND (15)
------------------------------------------------------------
⚠️  [WARNING] Function has high cyclomatic complexity
  File: internal/processor/transform.py:45
  Function: process_complex_data
  Complexity: 15 (threshold: 10)

⚠️  [WARNING] Function has too many parameters
  File: internal/server/handler.py:123
  Function: handle_request
  Parameters: 7 (threshold: 5)

ℹ️  [INFO] Magic number should be replaced with a named constant: 1000
  File: pkg/utils/helpers.py:42
  Function: calculate_limit

LARGEST FILES
------------------------------------------------------------
  1.  internal/server/handler.py         687 lines
  2.  pkg/database/migrations.py         542 lines
  3.  internal/api/routes.py             498 lines

MOST COMPLEX FUNCTIONS
------------------------------------------------------------
  1.  process_complex_data    CC=15  82 lines   internal/processor/transform.py
  2.  validate_input          CC=12  54 lines   pkg/validator/rules.py
  3.  handle_request          CC=11  95 lines   internal/server/handler.py

Analysis complete.

Architecture

The tool follows a clean, extensible architecture with a language provider system:

CLI (Cobra) → Orchestrator → Language Provider → Parser → Analyzer → Reporter
                  ↓                  ↓               ↓         ↓          ↓
              Storage           Detector Runner  FileMetrics  Issues   Multiple
                  ↓                                  ↓                  Formats
              Comparison                         Coverage Runner
                                                 Dependency Analyzer

Components

Language Provider: Abstracts language-specific parsing and analysis
- Go Provider: Uses Go's go/ast package
- Python Provider: Uses tree-sitter for parsing
- JavaScript/TypeScript Provider: Uses tree-sitter with TypeScript grammar
Parser: Extracts metrics (LOC, functions, imports, complexity) per language
Analyzer: Aggregates metrics, applies thresholds, coordinates sub-analyzers
- Detector Runner: Language-specific anti-pattern detection
- Coverage Runner: Language-specific test coverage (Go, JavaScript/TypeScript)
- Dependency Analyzer: Language-specific dependency analysis (Go, JavaScript/TypeScript)
Reporter: Formats and outputs results in console, Markdown, JSON, or HTML
Storage: Persists reports for historical tracking (file or SQLite backend)
Comparator: Compares current and previous reports, detects trends
Orchestrator: Coordinates the complete analysis pipeline
Config: Multi-level configuration (defaults → file → env → CLI flags)

All major components implement interfaces for easy testing and extensibility.

Project Structure

code-review-assistant/
├── cmd/                          # CLI commands
│   ├── root.go
│   └── analyze.go
├── internal/
│   ├── language/                 # Language provider system
│   │   ├── language.go           # Core interfaces
│   │   ├── registry.go           # Language registration & detection
│   │   ├── golang/               # Go language support
│   │   │   ├── provider.go
│   │   │   └── detectors.go
│   │   ├── python/               # Python language support
│   │   │   ├── provider.go
│   │   │   ├── parser.go
│   │   │   └── detectors.go
│   │   └── javascript/           # JavaScript/TypeScript language support
│   │       ├── provider.go
│   │       ├── parser.go
│   │       ├── detectors.go
│   │       ├── coverage.go
│   │       └── dependencies.go
│   ├── parser/                   # Go AST parsing (legacy, used by Go provider)
│   ├── analyzer/                 # Analysis and aggregation logic
│   │   └── detectors/            # Anti-pattern detectors
│   ├── coverage/                 # Test coverage analysis (Go)
│   ├── dependencies/             # Dependency analysis (Go)
│   ├── comparison/               # Historical comparison logic
│   ├── reporter/                 # Report formatting
│   ├── storage/                  # Persistent storage
│   ├── git/                      # Git metadata extraction
│   ├── orchestrator/             # Pipeline coordination
│   ├── config/                   # Configuration management
│   ├── status/                   # Live status reporting
│   └── constants/                # Shared constants
├── testdata/
│   ├── sample/                   # Go test fixtures
│   ├── python/                   # Python test fixtures
│   └── javascript/               # JavaScript/TypeScript test fixtures
├── main.go
└── README.md

Development

Running Tests

# Run all tests (fast - skips slow integration tests)
go test -short ./...

# Run all tests including slow integration tests
go test ./...

# Run with coverage
go test -short -cover ./...

# Generate HTML coverage report
go test -short -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Adding a New Language

Create a new package under internal/language/<lang>/
Implement the language.Language interface:
- Name() - Language identifier (e.g., "typescript")
- DisplayName() - Human-readable name (e.g., "TypeScript")
- Extensions() - File extensions (e.g., []string{".ts", ".tsx"})
- DefaultExcludePatterns() - Language-specific excludes
- Parser() - Returns a parser.Parser implementation
- DetectorRunner() - Returns anti-pattern detector
- CoverageRunner() - Returns coverage analyzer (or nil)
- DependencyAnalyzer() - Returns dependency analyzer (or nil)
Register in init() via language.Register(&YourLanguage{})
Import the package in internal/orchestrator/orchestrator.go
Update language detection in internal/language/registry.go

CI/CD Integration

The JSON output format makes it easy to integrate with CI/CD pipelines:

# GitHub Actions example
- name: Analyze Code Quality
  run: |
    code-review-assistant analyze . \
      --format json \
      --output-file report.json \
      --save-report \
      --compare

Troubleshooting

Language Detection Fails

If auto-detection doesn't find your project language:

# Use explicit language selection
code-review-assistant analyze . --language python

Or add a manifest file (go.mod, requirements.txt, etc.) to your project root.

CGO Errors During Build

Python support requires tree-sitter which needs CGO:

# Ensure CGO is enabled
CGO_ENABLED=1 go build -o code-review-assistant

# On macOS, install Xcode command line tools
xcode-select --install

# On Linux, install build-essential
sudo apt-get install build-essential

Exclude Generated Files

Add to config.yaml or use CLI:

code-review-assistant analyze . --exclude "generated/**" --exclude "**/*.pb.go"

Storage Issues

If you encounter storage errors, try using a custom path:

code-review-assistant analyze . --save-report --storage-path /custom/path

Roadmap

Future enhancements will be prioritized based on user feedback:

Additional language support (Rust, Java, C#, etc.)
Git history integration and code churn detection
Multi-repository analysis
Custom rules engine with plugin support

Have a feature request? Open an issue to let us know!

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE.md for details

Author

Daniel Munoz

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
cmd		cmd
config		config
examples		examples
internal		internal
testdata		testdata
.gitignore		.gitignore
CODE_QUALITY_IMPROVEMENTS.md		CODE_QUALITY_IMPROVEMENTS.md
IMPROVEMENTS.md		IMPROVEMENTS.md
LICENSE.md		LICENSE.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
integration_test.go		integration_test.go
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

Code Review Assistant

Supported Languages

Features

Multi-Language Support

Code Metrics & Analysis

Anti-Pattern Detection

Test Coverage Integration (Go)

Dependency Analysis (Go)

Multiple Output Formats

Persistent Storage & Historical Tracking

Historical Comparison

Flexible Configuration

Installation

Quick Start

Analyze with Auto-Detection

Explicit Language Selection

Output Formats

Historical Tracking

Language-Specific Features

Go

Python

JavaScript/TypeScript

Configuration

CLI Reference

analyze

Example Output

Console Output

Architecture

Components

Project Structure

Development

Running Tests

Adding a New Language

CI/CD Integration

Troubleshooting

Language Detection Fails

CGO Errors During Build

Exclude Generated Files

Storage Issues

Roadmap

Contributing

License

Author

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 14

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages