🏠 Gorphanage

A home for finding Go's lost code. Discover orphaned symbols with surgical precision using advanced reachability analysis.

Gorphanage uses reachability analysis to identify truly dead code in Go projects. Unlike simple grep-based tools, it traces execution paths from main() functions to find symbols that are genuinely unreachable.

✨ Features

🎯 Precise Detection - Uses Go's type system and AST for analysis
🚀 Reachability Tracing - BFS algorithm starting from main package entry points
📊 Smart Analysis - Handles complex dependency chains and indirect references
🛠️ Professional CLI - Built with Cobra & Viper for excellent UX
⚙️ Flexible Configuration - YAML config files, environment variables, and CLI flags
🎨 Multiple Output Formats - Human-readable terminal output and JSON for tooling
📋 Smart Exclusions - Exclude vendor code, generated files, and custom patterns
⚡ Fast & Reliable - Leverages the same engine that powers gopls

🚀 Installation

Option 1: Install from Source (Recommended)

go install github.com/mirrir0/gorphanage@latest

Option 2: Install Script

curl -sSL https://raw.githubusercontent.com/mirrir0/gorphanage/main/install.sh | bash

Option 3: Clone and Build

git clone https://github.com/mirrir0/gorphanage.git
cd gorphanage
make install

Option 4: Download Pre-built Binaries

Download the latest release for your platform from the releases page.

🔧 Quick Start

Basic Usage

# Analyze current directory
gorphanage .

# Analyze specific project
gorphanage /path/to/your/go/project

# Verbose output with progress
gorphanage --verbose .

# JSON output for tooling integration
gorphanage --json . > orphans.json

Advanced Usage

# Exclude specific packages
gorphanage --exclude "vendor/*,*.pb.go" .

# Include test files in analysis
gorphanage --include-tests .

# Multiple exclusion patterns
gorphanage -e vendor -e generated -e "*.pb.go" .

# Use custom config file
gorphanage --config ./custom-config.yaml .

📊 Example Output

Clean Project

$ gorphanage .
🔍 Analyzing project at: /home/user/myproject
📦 Loaded 8 packages
🔍 Found 147 symbols
📦 Found 2 main package(s)
🔍 Tracing reachability from main packages...
📊 Reachability analysis: 132/147 symbols reachable from main packages

✅ No orphaned code found!
All symbols are reachable from main package entry points.

Issues Found

$ gorphanage --verbose .
🔍 Analyzing project at: /home/user/myproject
📦 Loaded 8 packages
🔍 Found 147 symbols
📦 Found 2 main package(s)
    github.com/user/myproject/cmd/server
    github.com/user/myproject/cmd/client
🔍 Tracing reachability from main packages...
🎯 Starting with 6 entry points
📊 Reachability analysis: 132/147 symbols reachable from main packages

🗑️  ORPHANED CODE ANALYSIS
Found 15 symbols that are NOT reachable from any main package:

=== Functions ===
  📍 processLegacyData (private) - internal/legacy.go:67:1
  📍 ExportedButUnused (exported) - pkg/api.go:34:1
  📍 helperFunc (private) - utils/string.go:123:1

=== Types ===
  📍 OldConfig (exported) - config/deprecated.go:18:1
  📍 internalState (private) - state/manager.go:45:1

=== Variables ===
  📍 debugFlag (private) - main.go:15:1

💡 These symbols are not reachable from any main() or init() function.
💡 Test functions are excluded as they have separate entry points.
💡 Analysis based on 2 main package(s) found in the project.

📊 Analysis Summary:
  • Total symbols: 147
  • Reachable symbols: 132
  • Orphaned symbols: 15
  • Orphan rate: 10.2%

JSON Output

$ gorphanage --json .
{
  "project_path": "/home/user/myproject",
  "total_symbols": 147,
  "reachable_symbols": 132,
  "main_packages": 2,
  "excluded_packages": ["vendor/*", "*.pb.go"],
  "included_tests": false,
  "orphaned_symbols": [
    {
      "name": "processLegacyData",
      "kind": "function",
      "file": "/home/user/myproject/internal/legacy.go",
      "start": { "line": 67, "column": 1 },
      "end": { "line": 74, "column": 2 },
      "exported": false,
      "package": "github.com/user/myproject/internal"
    }
  ]
}

⚙️ Configuration

Configuration File

Create a configuration file for persistent settings:

# Initialize default config
gorphanage config init

# Show current configuration
gorphanage config show

Example ~/.gorphanage.yaml:

# Output settings
json: false
verbose: false

# Analysis options
include-tests: false

# Exclude patterns (glob patterns for package paths)
exclude:
  - "vendor/*"              # Vendor dependencies
  - "*.pb.go"               # Protocol buffer generated files
  - "*_generated.go"        # Generated Go files
  - "third_party/*"         # Third-party code
  - "mocks/*"               # Mock implementations
  - "testdata/*"            # Test data directories

Environment Variables

export GORPHANAGE_VERBOSE=true
export GORPHANAGE_EXCLUDE="vendor/*,generated/*"
export GORPHANAGE_JSON=true
gorphanage .  # Uses environment settings

Command Line Flags

Usage: gorphanage [flags] <project-path>

Flags:
  -e, --exclude strings      exclude packages matching these patterns
  -h, --help                help for gorphanage
      --include-tests       include test files in analysis
      --json                output results in JSON format
  -v, --verbose             verbose output
      --version             version for gorphanage

Global Flags:
      --config string       config file (default is $HOME/.gorphanage.yaml)

🎯 How It Works

Gorphanage uses a sophisticated reachability analysis algorithm:

📦 Package Discovery - Loads all Go packages with full type information
🔍 Symbol Mapping - Identifies all functions, types, variables, and constants
🎯 Entry Point Detection - Finds main() and init() functions as starting points
🌊 BFS Traversal - Traces all possible execution paths from entry points
💀 Orphan Detection - Reports symbols not reached during traversal

Why This Approach?

Traditional tools count references, but Gorphanage understands execution flow:

// ❌ Simple tools miss this
func main() {
    if false {
        deadFunction() // This is actually dead!
    }
}

// ✅ Gorphanage catches it
// Uses control flow analysis, not just reference counting

🛡️ Safety Features

🧪 Test-Aware - Automatically excludes Test*, Benchmark*, and Example* functions
📚 Library-Safe - Adapts behavior for library vs application projects
🔒 Conservative - When in doubt, preserves code rather than flagging it
📍 Precise Locations - Shows exact file and line numbers for easy cleanup
🎨 Smart Filtering - Configurable exclusion patterns for generated code

🔧 CI/CD Integration

GitHub Actions

name: Dead Code Check
on: [push, pull_request]

jobs:
  orphan-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-go@v4
      with:
        go-version: '1.21'
    
    - name: Install Gorphanage
      run: go install github.com/yourusername/gorphanage@latest
    
    - name: Check for orphaned code
      run: |
        gorphanage --json . > orphans.json
        if [ "$(jq '.orphaned_symbols | length' orphans.json)" -gt 0 ]; then
          echo "❌ Orphaned code detected!"
          jq '.orphaned_symbols[] | "\(.file):\(.start.line): \(.name) (\(.kind))"' orphans.json
          exit 1
        fi
        echo "✅ No orphaned code found"

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
echo "🔍 Checking for orphaned code..."
gorphanage . || exit 1

Makefile Integration

.PHONY: check-orphans
check-orphans:
	@echo "🔍 Checking for orphaned code..."
	@gorphanage --json . | jq -e '.orphaned_symbols | length == 0' > /dev/null || \
		(echo "❌ Orphaned code found. Run 'gorphanage .' for details" && exit 1)
	@echo "✅ No orphaned code found"

🆚 Comparison

Tool	Method	Accuracy¹	Go-Aware	Config	JSON Output
Gorphanage	Reachability Analysis	99.9%	✅	✅	✅
`deadcode`	Reference Counting	85%	✅	❌	❌
`ineffassign`	Assignment Analysis	70%	✅	❌	❌
`grep -r "funcName"`	Text Search	60%	❌	❌	❌

📚 Advanced Features

Custom Entry Points

For complex applications with non-standard entry points:

# Future feature
entry-points:
  - "github.com/myorg/myproject/pkg/plugin.Init"
  - "github.com/myorg/myproject/pkg/server.Start"

Performance Tuning

# Future features
max-depth: 100
timeout: "10m"
parallel: true
cache: true

🤝 Contributing

We love contributions! Here's how to get started:

🍴 Fork the repository
🌿 Branch from main: git checkout -b feature/amazing-feature
📝 Commit your changes: git commit -m 'Add amazing feature'
🚀 Push to your fork: git push origin feature/amazing-feature
📬 Submit a Pull Request

Development Setup

git clone https://github.com/yourusername/gorphanage.git
cd gorphanage
make dev        # Build with race detection
make test       # Run tests
make lint       # Run linter

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Go Team - For the amazing go/packages and AST libraries
gopls - Inspiration for the analysis approach
Cobra & Viper - For excellent CLI framework
Community - All the contributors and users

Made with ❤️ for the Go community

Report Bug · Request Feature · Discussions

I Completely made this up. ↩

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
Makefile		Makefile
README.md		README.md
analyzer.go		analyzer.go
example.gorphanage.yaml		example.gorphanage.yaml
go.mod		go.mod
go.sum		go.sum
gorphanage		gorphanage
install.sh		install.sh
main.go		main.go
output.go		output.go
reachability.go		reachability.go
references.go		references.go
symbols.go		symbols.go
types.go		types.go

Navigation Menu

Repository files navigation

🏠 Gorphanage

✨ Features

🚀 Installation

Option 1: Install from Source (Recommended)

Option 2: Install Script

Option 3: Clone and Build

Option 4: Download Pre-built Binaries

🔧 Quick Start

Basic Usage

Advanced Usage

📊 Example Output

Clean Project

Issues Found

JSON Output

⚙️ Configuration

Configuration File

Environment Variables

Command Line Flags

🎯 How It Works

Why This Approach?

🛡️ Safety Features

🔧 CI/CD Integration

GitHub Actions

Pre-commit Hook

Makefile Integration

🆚 Comparison

📚 Advanced Features

Custom Entry Points

Performance Tuning

🤝 Contributing

Development Setup

📄 License

🙏 Acknowledgments

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🏠 Gorphanage

✨ Features

🚀 Installation

Option 1: Install from Source (Recommended)

Option 2: Install Script

Option 3: Clone and Build

Option 4: Download Pre-built Binaries

🔧 Quick Start

Basic Usage

Advanced Usage

📊 Example Output

Clean Project

Issues Found

JSON Output

⚙️ Configuration

Configuration File

Environment Variables

Command Line Flags

🎯 How It Works

Why This Approach?

🛡️ Safety Features

🔧 CI/CD Integration

GitHub Actions

Pre-commit Hook

Makefile Integration

🆚 Comparison

📚 Advanced Features

Custom Entry Points

Performance Tuning

🤝 Contributing

Development Setup

📄 License

🙏 Acknowledgments

Footnotes

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages