metripy 1.0.0
A Python tool to generate multi project, multi language code metric reports
License: MIT
Requires Python: >=3.11
Keywords: code metrics, multi-language, code analysis, git metrics, code visualization, software quality, static analysis, repository insights, developer productivity, codebase health, technical debt, language-agnostic

# Metripy
A multilanguage, multi project code metrics analysis tool. 

[![PyPI version](https://img.shields.io/pypi/v/metripy.svg)](https://pypi.org/project/metripy/)
[![Tests](https://img.shields.io/badge/tests-138%20passed-brightgreen)](./tests)
[![Coverage](https://codecov.io/gh/zimmer-yan/metripy/branch/main/graph/badge.svg)](https://codecov.io/gh/zimmer-yan/metripy)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/metripy.svg)](https://pypi.org/project/metripy/)


# Languages
Supported languages
- Python
- Php
- Typescript
- TBD

# Analysis types

## Code analysis
Analyses code with cyclomatic complexity, maintainability index, halstead metrics.

## Git analysis
Analyses git stats of the past months

## Dependeny analysis
Analyzses composer, npm or pip dependencies

More dependencies TBD

# Report formats

## Html
Generates an easy to read dashboard for each project.

<img src="docs/images/overview-tiles.png" alt="Dashboard Overview" width="100%">

### Project Index Page
When analyzing multiple projects, you can generate a central index page that provides an overview of all projects at a glance.

<img src="docs/images/html-index.png" alt="HTML Index Overview" width="100%">

Configure with:

```json
{
    "configs": { /* multiple project configs */ },
    "html_index": "./build/index.html"
}
```

The index page displays:
- Aggregate statistics across all projects (total LOC, files, avg complexity, etc.)
- Project cards with individual metrics and health status
- Links to each project's detailed HTML report

<img src="docs/images/html-index-projects.png" alt="Project Cards" width="100%">

### Files Analysis

<img src="docs/images/files.png" alt="Files Analysis" width="100%">

### Top Offenders

<img src="docs/images/top-offenders.png" alt="Top Offenders" width="100%">

## Csv
Exports simple csv

## Json
Dumps full result into json

## Cli
Prints comprehensive overview directly to the terminal with color-coded visualizations:
- Stacked bar charts for all key metrics
- Top offenders tables (worst files and functions)
- Coupling and instability metrics
- Code smells summary
- Git and dependency metrics (when enabled) 

# Metrics

## Lines of code
The total number of lines in your source code, including comments and blank lines.

## Cyclomatic Complexity
A measure of the number of independent paths through your code.

## Cognitive Complexity
A measure of how difficult code is to understand based on its control flow and nesting.

## Maintainability Index
A composite metric that estimates how easy it is to maintain code, based on LOC, complexity, and comments.

## Average Method Size
The average number of lines per method or function in your codebase.

## Instability
A metric that measures how likely a module is to change based on its dependencies (ratio of efferent to afferent couplings).

## LCOM4
A metric that measures how well the methods of a class are related to each other. It checks if methods share common attributes, indicating cohesion.

# Configuration
Configuration is for the moment only possible with the `--config=<file>.json` option. More TBD

Sample configuraiton:
```json
{
    "configs": {
        "metripy": {
            "base_path": "./", // base path to look at
            "includes": [
                "metripy/" // paths to include from the base path on
            ],
            "excludes": [
                "__pycache__" // exclude patterns of paths / files
            ],
            "extensions": [
                "py" // file extensions to look at
            ],
            "git": { // if git is set, analyzes git history
                "branch": "main" // git branch to look at
            },
            "composer": true, // looks for base_path/composer.json and analyzes dependencies - for php projects
            "npm": true, // looks for base_path/package.json and analyzes dependencies - for ts/js projects
            "pip": true,
            // looks for base_path/requirements.txt or base_path/pyproject.toml and analyzes dependencies - for python projects
            "reports": {
                "html": "./build/report/metripy", // report should be put into this directory
                "json-git": "./build/json-report/metripy-git.json" // file where to put git json report
                // more types of reports TBA
            }
        },
        // next project name: { next config... } 
    },
    "html_index": "./build/index.html" // optional: generates a central overview page for all projects
}
```

## Configuration for only git stats
```json
{
    "configs": {
        "metripy-git": {
            "base_path": "./",
            "git": {
                "branch": "main"
            },
            "reports": {
                "json-git": "./build/json-report/metripy-git.json"
            }
        }
    }
}
```

## Exit Conditions (Quality Gates)

Define conditions to fail the analysis with specific exit codes. Useful for CI/CD pipelines.

```json
{
    "configs": { ... },
    "failure": {
        "1": [
            {
                "value": "function_cyclomatic_complexity",
                "severity": "critical",
                "amount": 10
            }
        ]
    }
}
```

This example exits with code 1 if there are 10 or more functions with critical cyclomatic complexity.

### Available metrics
- File level: `file_loc`, `file_cyclomatic_complexity`, `file_maintainability_index`, `file_cognitive_complexity`
- Class level: `class_loc`, `class_cyclomatic_complexity`, `class_lcom4`
- Function level: `function_loc`, `function_cyclomatic_complexity`, `function_maintainability_index`, `function_cognitive_complexity`

### Severity levels
`good`, `ok`, `warning`, `critical`

See the [Configuration Guide](docs/configuration.md) for more details.