devscope 0.1.1

A zero-config tool that analyzes any codebase and outputs beautiful terminal reports with core repository intelligence

Devscope

Universal Codebase Intelligence for CI & Teams

Analyze any repository in seconds. Get a maintainability grade, risk level, onboarding difficulty, and a CI-ready quality gate — zero configuration.

🚀 Install in 10 Seconds

pipx install devscope
devscope scan .

Or install from source:

git clone https://github.com/EhsanAzish80/Devscope.git
cd Devscope
uv sync
uv run devscope scan .

That's it. No config files. No setup. Just intelligence.

Try it now:

devscope summary --compact

Devscope: B · Low risk · Easy onboarding · 1.00 tests · 0.06s ⚡

---

🎯 Why devscope?

Feature	devscope	cloc	tokei
Maintainability grade	✅ A-F scoring	❌	❌
CI quality gate	✅ Exit codes	❌	❌
Multi-language repo intelligence	✅ Full context	⚠️ Basic	⚠️ Basic
Shareable PR summaries	✅ Markdown + badges	❌	❌
Intelligent caching	✅ 10-20x speedup	❌	❌
Risk & onboarding metrics	✅ Built-in	❌	❌
Test coverage detection	✅ Automatic	❌	❌

---

🌍 Real-World Examples

See devscope analyzing popular open-source projects:

fastapi

Devscope: A · Low risk · Moderate onboarding · 1.01 tests · 3.38s ⚡

django

Devscope: B · Low risk · Hard onboarding · 2.79 tests · 7.29s ⚡

typer

Devscope: A · Low risk · Moderate onboarding · 0.89 tests · 0.66s ⚡

requests

Devscope: B · Low risk · Easy onboarding · 1.91 tests · 0.15s ⚡

Benchmarks run on GitHub Actions (2-core Linux VM).

---

⚡ Blazing Fast

First scan:

$ devscope scan .
✓ Analysis complete in 2.45s

Cached scan (same repo):

$ devscope scan .
✓ Analysis complete in 0.15s (cache: 100% hit rate, ~2.3s saved)

10-20x faster on large repos. Automatic cache invalidation when files change.

---

🧪 Devscope Analyzing Itself

This repository is continuously analyzed by devscope.

🔍 Devscope Report

Repo: Devscope
Files: 37
Lines: 7,710
Languages: Python (70%) · Shell (14%) · Markdown (8%)

Health: B (82.5)
Risk: Low
Onboarding: Easy

Tests: 1.00 ratio
Last commit: today

Top hotspot: README.md (568 LOC, Very large file (568 LOC), No nearby tests)

⚡ Scan time: 0.06s

This report is automatically updated on every push.

---

💡 Use Cases

• CI quality gate — Fail builds on grade drops (--fail-under B)
• PR health comment — One-line summary in every PR (devscope summary --compact)
• Client code audit — Instant maintainability report for stakeholders
• Monorepo onboarding — Estimate ramp-up time for new engineers

---

📝 Shareable Summaries (The Viral Feature)

Embed in Your README

devscope summary --badges > HEALTH.md

Output:

## 🔍 Devscope Report

![Maintainability](https://img.shields.io/badge/maintainability-B-green)
![Risk](https://img.shields.io/badge/risk-Low-green)
![Onboarding](https://img.shields.io/badge/onboarding-Easy-blue)

**Health:** B (82.1) · **Risk:** Low · **Onboarding:** Easy  
**Files:** 1,247 · **Lines:** 45,892 · **Tests:** 0.78 ratio

⚡ Scan time: 0.82s (cache: 100% hit rate)

PR Comment (GitHub Actions)

- name: Add health check to PR
  run: |
    devscope summary --compact >> $GITHUB_STEP_SUMMARY

Output:
Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

JSON for Bots

devscope summary --json | jq '.health'

Perfect for Slack notifications, status pages, or custom integrations.

---

📊 Output Examples

Terminal (Default)

╔═══════════════════════════════════════╗
║     devscope v0.1.0                   ║
║  Code Intelligence at a glance        ║
╚═══════════════════════════════════════╝

📊 my-project

Repository          my-project
Health Grade        B (82.5)
Risk Level          Low
Onboarding          Easy

Total Files         1,247
Total Lines         45,892

Languages
  Python            45.2%
  TypeScript        32.8%
  JavaScript        12.1%

Tests               0.78 ratio
Top Hotspot         src/analyzer.py (321 LOC)

✓ Analysis complete in 0.82s

Compact (for PRs)

Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

JSON (for automation)

{
  "health_score": {
    "maintainability_grade": "B",
    "risk_level": "Low",
    "onboarding_difficulty": "Easy",
    "score_breakdown": {
      "overall": 82.5,
      "complexity": 80.2,
      "tests": 78.0,
      "git_activity": 90.0
    }
  },
  "total_files": 1247,
  "total_lines": 45892,
  "test_ratio": 0.78,
  "scan_time": 0.82
}

📋 Full JSON Schema

{
  "analysis": {
    "complexity": {
      "avg_file_size": 368.5,
      "deep_nesting_warning": false,
      "largest_files": [
        {"file_path": "src/analyzer.py", "size_bytes": 9856}
      ],
      "max_directory_depth": 3
    },
    "dependencies": [
      {
        "ecosystem": "Python",
        "manifest_file": "pyproject.toml",
        "dependency_count": 8,
        "dependencies": ["click", "rich", "gitpython", "pathspec"]
      }
    ],
    "git_metrics": {
      "is_git_repo": true,
      "commit_count": 42,
      "contributor_count": 2,
      "days_since_last_commit": 0
    },
    "health_score": {
      "maintainability_grade": "B",
      "risk_level": "Low",
      "onboarding_difficulty": "Easy",
      "score_breakdown": {
        "overall": 82.5,
        "complexity": 80.2,
        "structure": 90.0,
        "tests": 78.0,
        "git_activity": 90.0,
        "hotspots": 85.0
      }
    },
    "hotspots": [
      {
        "file_path": "src/analyzer.py",
        "lines_of_code": 321,
        "depth": 2,
        "has_nearby_tests": true,
        "reason": "Large file with high complexity",
        "risk_score": 75.3
      }
    ],
    "languages": {
      "Python": 52.9,
      "Markdown": 17.6,
      "Shell": 11.8
    },
    "test_metrics": {
      "has_tests": true,
      "test_file_count": 8,
      "source_file_count": 12,
      "test_ratio": 0.667
    },
    "cache_stats": {
      "enabled": true,
      "hits": 55,
      "misses": 5,
      "total_files": 60,
      "hit_rate": 91.67,
      "time_saved_estimate": 0.005
    },
    "total_files": 60,
    "total_lines": 3800,
    "scan_time": 0.15
  },
  "devscope_version": "0.1.0",
  "schema_version": "1.0"
}

---

🤖 CI/CD Integration

Quality Gates with Exit Codes

Exit codes:

• 0 = Analysis passed all thresholds
• 1 = Runtime error (invalid path, permissions)
• 2 = Threshold violated (grade/risk/onboarding)

GitHub Actions

- name: Code health check
  run: |
    devscope ci . \
      --fail-under B \
      --max-risk Medium \
      --max-onboarding Moderate

If health drops below B, the job fails with exit code 2.

GitLab CI

analyze:
  script:
    - devscope ci . --fail-under B --json > analysis.json
  artifacts:
    reports:
      codequality: analysis.json

Shell Script

#!/bin/bash
devscope ci . --fail-under C

if [ $? -eq 2 ]; then
  echo "❌ Code quality below threshold"
  exit 1
fi

---

📖 Command Reference

devscope scan

Analyze a codebase with beautiful terminal output.

devscope scan                    # Current directory
devscope scan /path/to/project   # Specific path
devscope scan --json             # JSON output
devscope scan --basic            # Fast scan (no intelligence)
devscope scan --no-git           # Skip git detection
devscope scan --no-cache         # Disable caching
devscope scan --clear-cache      # Clear cache before scan

devscope ci

CI-optimized command (always outputs JSON).

devscope ci                      # Current directory
devscope ci --fail-under B       # Fail if grade < B
devscope ci --max-risk High      # Fail if risk > High
devscope ci --max-onboarding Hard   # Fail if onboarding > Hard

devscope summary

Generate shareable summaries.

devscope summary                 # Markdown report
devscope summary --badges        # Include shields.io badges
devscope summary --compact       # One-line summary
devscope summary --json          # JSON with badges

---

🏆 Status & Quality

Metric	Value
Tests	133 passing
Coverage	82%
Type checking	mypy strict mode
Platforms	Linux · macOS · Windows
Python	3.9+

This project follows rigorous engineering standards:

• ✅ Full type annotations
• ✅ Comprehensive test suite
• ✅ Zero runtime dependencies conflicts
• ✅ Cross-platform compatibility tested

---

🗺️ Roadmap

✅ Completed

• Maintainability grading (A-F)
• Risk & onboarding assessment
• CI quality gates with exit codes
• Intelligent caching (10-20x speedup)
• Shareable markdown summaries
• Shields.io badge generation
• Test coverage detection
• JSON automation API

🚀 Next

• Configuration file (.devscope.yml)
• Historical trend tracking
• Team analytics dashboard
• Security scanning (CVE detection)

---

🛠️ Development

Quick Start

git clone https://github.com/EhsanAzish80/Devscope.git
cd Devscope
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-extras
uv run devscope scan

Running Tests

uv run pytest                    # All tests
uv run pytest --cov              # With coverage
uv run pytest tests/test_analyzer.py   # Specific file

Code Quality

uv run ruff format .             # Format
uv run ruff check .              # Lint
uv run mypy src/devscope         # Type check

Project Structure

devscope/
├── src/devscope/
│   ├── cli.py          # Command-line interface
│   ├── analyzer.py     # Core analysis engine
│   ├── models.py       # Type-safe data models
│   ├── formatters.py   # Summary & badge generation
│   ├── cache.py        # Intelligent caching layer
│   └── utils.py        # Shared utilities
├── tests/
│   ├── test_analyzer.py
│   ├── test_cli.py
│   ├── test_cache.py
│   ├── test_summary.py
│   └── test_ci_thresholds.py
└── pyproject.toml      # Dependencies & config

---

🏗️ Architecture

Design principles:

1. Separation of concerns — CLI, analysis, formatting isolated
2. Type safety — Full mypy strict mode compliance
3. Performance — Smart caching with automatic invalidation
4. Extensibility — Plugin-ready analyzer system
5. User experience — Beautiful terminal output with Rich

Core components:

• Analyzer — File system traversal, language detection, metrics calculation
• Cache Manager — File metadata caching with invalidation on change
• Formatters — Output generation (terminal/JSON/markdown/compact)
• CLI — Click-based interface with rich error handling

---

📄 License

MIT License - see LICENSE file.

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Run tests (./scripts/check.sh)
4. Submit a PR

For major changes, open an issue first.

---

🙏 Acknowledgments

Built with:

• uv — Fast dependency management
• Rich — Beautiful terminal UI
• Click — CLI framework

Inspired by tokei and cloc.

---

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation

---

Made with ❤️ for developers who ship