ciqar 1.1.0
Ciqar is a tool for creating reports from different code quality analyzers output.
Requires Python: >=3.12
Keywords: linter, report, code analysis, code quality

# Ciqar

Ciqar is a tool for creating useful and (at least somewhat) pretty HTML reports from different code
quality analyzers output in case the analyzers do not provide sufficient report or you want a uniform
style. The report is generated from a Jinja template so that it can be customized. At the moment, MyPy
and Pyright are supported as analyzers.

The name is made up from how we pronounced the earliest project name `cqr` (which is the abbreviation
for *code quality reports*) as a word. Do not confuse it with `Cigar` 😉

Have a look at two HTML reports for Ciqar version 0.1.0 (some violations were added purposely 😉):
 - MyPy: https://aardjon.codeberg.page/ciqar/reports/mypy/
 - Pyright: https://aardjon.codeberg.page/ciqar/reports/pyright/

[![Build status](https://ci.appveyor.com/api/projects/status/11bkqbw0exo6y76s?svg=true)](https://ci.appveyor.com/project/Aardjon/ciqar)


## Installation

Ciqar releases are available on PyPI, so you can easily install it via `pip`:
```
pip install ciqar
```

Alternatively you can install from source code:
```
cd /path/to/ciqar/source
pip install -e .
```


## Usage

Tell Ciqar the location of the analyzer output and the paths to search for source files. The search path
configuration is usually the same as for your static code analyzer.

```
ciqar --analyzer-result mypy:/path/to/mypy.log --source /path/to/src/dir --output /path/to/destination/dir
```

The "Analyzer result URL" (`--analyzer-result`) is a URL string with the *scheme* part defining which code
analyzer has been used and the *path* containing the path to result data. The kind of the path object (e.g.
directory or file, file type) depends on the chosen analyzer. Currently supported analyzers:

| Analyzer | URL Scheme | URL path                                                   |
|----------|------------|------------------------------------------------------------|
| MyPy     | "mypy"     | Single file with the stdout output of the MyPy run.        |
| Pyright  | "pyright"  | Single JSON file generated by `pyright --outputjson`.      |
| ruff     | "ruff"     | Single JSON file generated by `ruff --output-format json`. |


`--source` may be provided several times to search more than one directory. In addition (or alternatively)
it is also possible to exclude files or directories from the configured search paths with the `--exclude`
option, which may also be provided several times:

```
ciqar --source /path/to/src/dir --exclude /path/to/src/dir/examples --exclude /path/to/src/dir/snippet.py --analyzer-result [...] --output [...]
```

The `--output` option simply defines the directory to write the report into. Any existing files will be overwritten.

The optional `--template` parameter defines the report template to use, allowing to generate different
kinds of reports. The template name must be specified by its name:
```
ciqar -r mypy:mypy.log -s src -o output -t html_detailed
```

At the moment the following report templates are available:

| Template name   | Description                                                                    |
|-----------------|--------------------------------------------------------------------------------|
| html_detailed   | Detailed HTML report including file lists, rule list and source code listings. |
| html_singlepage | More compact, single-page HTML report listing all violations.                  |


### Examples (run from the repository root)

Create MyPy report for Ciqar:
```
mypy --config-file mypy.ini src test | tee mypy.log
ciqar -r mypy:mypy.log -s src -s test -o report-mypy
```

Create Pyright report for Ciqar:
```
pyright --outputjson src test > pyright.json
ciqar -r pyright:pyright.json -s src -s test -o report-pyright
```

Create ruff report for Ciqar:
```
ruff check src/ test/ --output-format json > ruff.json
ciqar -r ruff:ruff.json -s src -s test -o report-ruff
```


## Some hints

For MyPy reports, it is necessary to set `hide_error_codes = False` in the config (which is default).