Metadata-Version: 2.4
Name: techlens-metrics
Version: 0.4.0
Summary: Calculate code metrics in various languages
Project-URL: Homepage, https://www.crosslaketech.com/
Author-email: Crosslake Technologies <techlens@crosslaketech.com>
License-Expression: CC-BY-NC-4.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Free for non-commercial use
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: chardet>=5.2.0
Requires-Dist: httpx[http2]~=0.28.1
Requires-Dist: pygments==2.19.2
Requires-Dist: pygount
Requires-Dist: techlens-cache-utils==0.2.0
Requires-Dist: techlens-pygments-tsx==0.3.0
Provides-Extra: dev
Requires-Dist: black>=24.1.1; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/markdown

# Modern Metric
Calculate code metrics and complexity in various languages

## Purpose

This tool tries to calculate the following metrics for many, many programming languages

* Comment to Code percentage
* Cyclomatic complexity according to McCabe
* Difficulty according to Halstead
* Effort according to Halstead
* Fan-Out
* Lines of code
* Maintainability index
* Metric according to pylint
* Metric according to TIOBE
* Number of delivered bugs according to Halstead
* Time required to program according to Halstead
* Volume according to Halstead

This tool was heavily inspired by [metrics](https://github.com/markfink/metrics)

## Requirements

* python3
* [chardet](https://pypi.org/project/chardet/)
* [Pygments](http://pygments.org/)

## Installation

### PyPi

simply run

```sh
pip3 install modernmetric
```

### From source

* git clone this repository
* cd to \<clone folder\>
* Install the needed requirements by running ```pip3 install -r requirements.txt```
* run `python3 setup.py build`

## Usage

```shell
usage: modernmetric [-h] [--warn_compiler WARN_COMPILER]
                   [--warn_duplication WARN_DUPLICATION]
                   [--warn_functional WARN_FUNCTIONAL]
                   [--warn_standard WARN_STANDARD]
                   [--warn_security WARN_SECURITY] [--coverage COVERAGE]
                   [--bugpredict {old,new}]
                   [--maintindex {sei,classic,microsoft}]
                   [--file=path_to_filelist]
                   AND/OR
                   files [files ...]

Calculate code metrics in various languages

positional arguments:
  files                 Files to parse

optional arguments:
  -h, --help            show this help message and exit
  --file=path_to_filelist
                    Path to JSON filelist to scan. Format is:
                    [
                        {
                            "name": "test.c",
                            "path": "../testfiles/test.c"
                        }
                    ]
  --output_file=path to output, optional
  --warn_compiler WARN_COMPILER
                        File(s) holding information about compiler warnings
  --warn_duplication WARN_DUPLICATION
                        File(s) holding information about code duplications
  --warn_functional WARN_FUNCTIONAL
                        File(s) holding information about static code analysis findings
  --warn_standard WARN_STANDARD
                        File(s) holding information about language standard violations
  --warn_security WARN_SECURITY
                        File(s) File(s) holding information about found security issue
  --coverage COVERAGE   File(s) with compiler warningsFile(s) holding information about testing coverage
  --bugpredict {old,new}
                        Method how to calculate the bug prediction
  --maintindex {sei,classic,microsoft}
                        Method how to calculate the maintainability index

Currently you could import files of the following types for --warn_* or --coverage

Following information can be read

    <file> = full path to file
    <content> = either a string
    <severity> = optional severity

    Note: you could also add a single line, then <content>
        has to be a number reflecting to total number of findings

File formats

csv: CSV file of following line format
     <file>,<content>,<severity>

json: JSON file
     <file>: {
         "content": <content>,
         "severity": <severity>
     }
```

By default tool guesses the content type by the filename, if that doesn't work for you please see below

## Output

Output will be written to stdout as json.

### Output structure

* `files` contains a list of each file passed by CLI
* `overall` contains the calculated values for all passed files
* `stats` contains the statistically calculated values over all files passed [see Statistical additions](#statistics)

#### Item structure

| item                  | description                                    | range    | recommendation |
| --------------------- | ---------------------------------------------- | -------- | -------------- |
| comment_ratio         | Comment to Code percentage                     | 0..100   | > 30.0         |
| cyclomatic_complexity | Cyclomatic complexity according to McCabe      | 0..(inf) | < 10           |
| fanout_external       | Number imports from out of tree modules        | 0..(inf) |                |
| fanout_internal       | Number imports from same source tree modules   | 0..(inf) |                |
| halstead_bugprop      | Number of delivered bugs according to Halstead | 0..(inf) | < 0.05         |
| halstead_difficulty   | Difficulty according to Halstead               | 0..(inf) |                |
| halstead_effort       | Effort according to Halstead                   | 0..(inf) |                |
| halstead_timerequired | Time required to program according to Halstead | 0..(inf) |                |
| halstead_volume       | Volume according to Halstead                   | 0..(inf) |                |
| lang                  | list of identified programming languages       | list     |                |
| loc                   | Lines of code                                  | 1..(inf) |                |
| maintainability_index | Maintainability index                          | 0..100   | > 80.0         |
| operands_sum          | Number of used operands                        | 1..(inf) |                |
| operands_uniq         | Number of unique used operands                 | 1..(inf) |                |
| operators_sum         | Number of used operators                       | 1..(inf) |                |
| operators_uniq        | Number of unique used operators                | 1..(inf) |                |
| pylint                | General quality score according to pylint      | 0..100   | > 80.0         |
| tiobe_compiler        | Compiler warnings score according to TIOBE     | 0..100   | > 90.0         |
| tiobe_complexity      | Complexity according to TIOBE                  | 0..100   | > 80.0         |
| tiobe_coverage        | Coverage according to TIOBE                    | 0..100   | > 80.0         |
| tiobe_duplication     | Code duplications score according to TIOBE     | 0..100   | > 80.0         |
| tiobe_fanout          | Fan-Out score according to TIOBE               | 0..100   | > 80.0         |
| tiobe_functional      | Functional defect score according to TIOBE     | 0..100   | > 90.0         |
| tiobe_security        | Security score according to TIOBE              | 0..100   | > 90.0         |
| tiobe_standard        | Language standard score according to TIOBE     | 0..100   | > 80.0         |
| tiobe                 | General quality score according to TIOBE       | 0..100   | > 80.0         |

#### Statistics

The item `stats` contains in addition to the above mentioned the following items, which by themselves contain all the items mentioned at [Item structure](#item-structure)

* `max` = the maximum value of all items of the metric
* `mean` = statistical mean over all items of the metric
* `median` = statistical median over all items of the metric
* `min` = the minimum value of all items of the metric
* `sd` = standard deviation over all items of the metric

## Further reading

* [Pygments](http://pygments.org/)

## Bugs & Contribution

Feel free to create issues or pull requests
