custolint 0.4.6
Another custom linter layer
License: MIT License
Keywords: static code analysis,linter,python,lint,coverage,flake8

.. COMMENT:
    script docs/conf.py will copy
    and alter this file into ./docs directory for sphinx documentations scopes

=========================
custolint - custom linter
=========================

|Custolint Logo|

Your current code-validation pipeline rules may be changed more easily using **custolint**.

|Documentation| |Python Code Coverage| |License|

.. | docs | | coverage(100%) |

**Source Code**: `<https://github.com/a-da/custolint>`_.

Custolint add new layer on top of:

- `PyLint <https://github.com/PyCQA/pylint>`_
- `Flake8 <https://github.com/PyCQA/flake8>`_
- `MyPy <https://github.com/python/mypy>`_
- `Python Coverage <https://github.com/nedbat/coveragepy>`_


Motivation
----------

You cannot just add a linter and activate 100% inspections when you have a large,
ancient codebase with thousands of lines.

|Boromir Meme|

Instead, you only make 1% of the checks available, which is really frustrating for a decent developer.

*You could enable those 100% checks just for your changes with "custolint"*.

Idea
----

.. TODO: draw a diagram.

Given we have a project alike this one, where we:

1. had added a function ``custolint/generics.py:filer_output``.
2. had modified the function ``custolint/git.py:_blame``

.. code-block:: bash
    :name: given example

    $ tree
    ...
    |-- src
    |   |-- custolint
    ...
    |   |   |-- generics.py <<<< 1
    |   |   |-- git.py      <<<< 2
    |   |   |-- mypy.py
    |   |   |-- pylint.py
    |   |   `-- typing.py
    |-- tests
    |   `-- test_custolint.py
    ...

When:

- **Detect affected files** with ``git diff`` and ``git blame``

  - ``custolint/git.py``
  - ``custolint/generics.py``

- **Run the linter** tool (pylint, flake8, mypy, coverage ...) with all available feature enables
  (the configuration have to be placed into  ``config.d/`` folder)
  only on changed affected files or parse log/result of the linter tool.

- **Match changed code** with the linters output, and consider only the match lines as failed lint criteria.
  It has to detect that ``custolint/generics.py:filer_output`` need unitest for coverage
  and ``custolint/git.py:_blame`` introduce a mypy typing issue.

Then:

- **Fail or Report** the build.

.. code-block:: bash

    $ coverage run --rcfile=config.d/.coveragerc -m pytest && \
        custolint coverage config.d/.coveragerc
    INFO:custolint.git:Execute git diff command 'git diff origin/main -U0 --diff-filter=ACMRTUXB'
    INFO:custolint.git:Git diff detected 16 filed affected
    INFO:custolint.coverage:execute coverage command: 'coverage report --data-file=.coverage --show-missing'
    src/custolint/git.py:66 not.committed.yet 2022-08-31

    $ custolint mypy
    INFO:custolint.mypy:MYPY COMPARE WITH 'main' branch
    INFO:custolint.git:Execute git diff command 'git diff origin/main -U0 --diff-filter=ACMRTUXB'
    INFO:custolint.git:Git diff detected 16 filed affected
    INFO:custolint.mypy:execute command 'mypy --config-file=config.d/mypy.ini @/tmp/f/59..000gq/T/tmp...'
    tests/test_custolint.py 31 Module has no attribute "bash"  [attr-defined] not.committed.yet 2022-08-31
    tests/test_custolint.py 125 Function is missing a return type annotation  [no-untyped-def] not.committed.yet 2022-08-31
    tests/test_custolint.py 140 Function is missing a return type annotation  [no-untyped-def] not.committed.yet 2022-08-31

Install
-------

See `Install dev version <docs/for_developers.rst>`_


How to run:
-----------

.. code-block::

    cd "${YOUR_CODE}/"

    # check typing
    custolint mypy

    # code smell checking with pylint
    custolint pylint

    # code smell checking with flake8
    custolint flake8

    # 100% coverage checking for new commits
    coverage run --rcfile=config.d/.coveragerc -m pytest
    custolint coverage config.d/.coverage


.. |Boromir Meme| image:: ./docs/_static/Boromir-meme.jpg
  :align: top
  :width: 100
  :alt: You cannot just take and (Boromir meme)

.. |Custolint Logo| image:: ./docs/_static/custolint-logo-the-future-by-RAP-studio.png
  :align: top
  :target: https://github.com/a-da/custolint
  :alt: Custolint logo

.. |Python Code Coverage| image:: https://codecov.io/github/a-da/custolint/branch/main/graph/badge.svg?token=MU42A9NAT2
  :target: https://codecov.io/github/a-da/custolint
  :alt: Python Code Coverage

.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: license.html
    :alt: License

.. |Documentation| image:: https://img.shields.io/readthedocs/custolint.svg
    :target: https://custolint.readthedocs.io/en/latest/
    :alt: Documentation


.. TODO: https://stackoverflow.com/a/13945797/1251677

Custolint

No Legal Copyright (c) 2022 is own by creator Danciuc Andrei.
All rights can can not reserved.

Using the MIT licence http://opensource.org/licenses/MIT

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.