|pypi| |test| |coverage|

========
pkgcheck
========

Dependencies
============

pkgcheck is developed alongside pkgcore_ and snakeoil_. Running pkgcheck from
git will often require both pkgcore and snakeoil from git as well.

For releases, see the required runtime dependencies_.

There are also several optional runtime dependencies that add or extend check
support in various ways if found on the host system including the following:

- git_: supports historical queries for git-based repos and commit-related checks
- requests_: supports various network-related checks
- Gentoo-PerlMod-Version_: supports Perl package version checks
- tree-sitter-bash_: used in checks that inspect the CST of ebuilds and
  eclasess. Must be language version >= 14.

Installing
==========

Installing latest pypi release::

    pip install pkgcheck

Installing from git::

    pip install https://github.com/pkgcore/pkgcheck/archive/master.tar.gz

Installing from a tarball::

    python setup.py install

Usage
=====

Most users will use pkgcheck on the command line via ``pkgcheck scan`` to
target ebuild repos. See the docs_ or the man page for more information on
running pkgcheck.

It's also possible to run pkgcheck natively from python. For example, to output
the results for a given ebuild repo:

.. code-block:: python

    from pkgcheck import scan

    for result in scan(['/path/to/ebuild/repo']):
        print(result)

This allows third party tools written in python to leverage pkgcheck's scanning
functionality for purposes such as CI or VCS commit support.

Tests
=====

Normal pytest is used, just execute::

    pytest

In addition, a tox config is provided so the testsuite can be run in a
virtualenv setup against all supported python versions. To run tests for all
environments just execute **tox** in the root directory of a repo or unpacked
tarball. Otherwise, for a specific python version execute something similar to
the following::

    tox -e py311

Adding new checks
=================

Adding a new check consists of 2 main parts: writing the logic and
documentation, and adding tests for the check.

Writing the logic
-----------------

1. Select the best file for the check under ``src/pkgcheck/checks/``.

2. Create new classes for the results:

   - You would need to select the correct result level (style, info, warning,
     error) - you might want to consult QA team.

   - You would need to select the correct context: category, package, version,
     profile, etc.

   - Add long user friendly documentation for the result.

   - Implement the ``desc`` property which is printed to the user.

3. Create a new class for the check:

   - Add long user friendly documentation for the result.

   - Put the source of input for the check. This is hard, so best case is to
     find similar check and copy the code.

   - Define the results it can return.

   - Implement the ``feed`` function.

Adding tests
------------

1. Select one of the repos under ``testdata/repos``. In most cases you would
   want ``standalone``.

2. Add the ebuild/category/test case you want to catch.

3. ``cd`` into this directory, and run ``pkgcheck scan --cache-dir /tmp -R JsonStream``.
   This should yield the results you want to catch (filter out what you expect).

4. Add the results to the test case under:
   ``testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/expected.json``

5. If you want to check the fix for the test case, ``git add`` the files under
   ``testdata/repos/${REPO}``, modify to fix the results, and using
   ``git diff testdata/repos/${REPO}`` collect the diff.

6. Copy similar patch, add the diff to the patch file, and fix file names, under:
   ``testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/fix.patch``


.. _pkgcore: https://github.com/pkgcore/pkgcore
.. _snakeoil: https://github.com/pkgcore/snakeoil
.. _dependencies: https://github.com/pkgcore/pkgcheck/blob/master/requirements/install.txt
.. _git: https://git-scm.com/
.. _requests: https://pypi.org/project/requests/
.. _Gentoo-PerlMod-version: https://metacpan.org/release/Gentoo-PerlMod-Version
.. _tree-sitter-bash: https://github.com/tree-sitter/tree-sitter-bash
.. _docs: https://pkgcore.github.io/pkgcheck/man/pkgcheck.html

.. |pypi| image:: https://img.shields.io/pypi/v/pkgcheck.svg
    :target: https://pypi.python.org/pypi/pkgcheck
.. |test| image:: https://github.com/pkgcore/pkgcheck/workflows/test/badge.svg
    :target: https://github.com/pkgcore/pkgcheck/actions?query=workflow%3A%22test%22
.. |coverage| image:: https://codecov.io/gh/pkgcore/pkgcheck/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/pkgcore/pkgcheck