CI/CD Integration with CodeScene's Delta Analysis
=================================================

.. include:: ../../../shared/integrations/pr-integration/delta.rst


Notify the Code Owners on Failed Quality Gates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As discussed in :doc:`/guides/social/knowledge-distribution`, CodeScene parses and includes code ownership information when present.
If you have this feature enabled, then CodeScene will include a mention of the code owners should a quality gate fail.
You see an example in :numref:`ci-cd-code-owners-jenkins`.

.. figure:: code-owners-jenkins.png
   :alt: CodeScene notifies code owners when a quality gate fails.
   :name: ci-cd-code-owners-jenkins

   CodeScene notifies code owners when a quality gate fails.

.. _The-REST-API-for-Delta-Analyses:

The REST API for Delta Analyses
-------------------------------

CodeScene provides out of the box integrations with code review platforms like GitHub, BitBucket, GitLab, etc.
In addition, CodeScene also provides an open REST API that lets you write custom integrations. The API is described below.

CodeScene lets you create a special `Bot` user role intended to consume the REST API. Login as administrator and create
a Bot user for each of your integration points as illustrated in :numref:`botuser`

.. figure:: BotUser.png
   :alt: Configure a Bot user
   :name: botuser

   Configure a Bot user for each of your integration points.

You trigger a Delta Analysis by POSTing a request to the REST endpoint specified in your analysis configuration as
illustrated in :numref:`restendpointconfig`.

.. figure:: RestEndpoint.png
   :alt: REST API endpoint
   :name: restendpointconfig

   Your analysis configuration specifies the REST endpoint to trigger a delta analysis.

The payload of the POST request specifies two required fields:

1. *commits*: This is a JSON array containing one or more commits. CodeScene will run a delta analysis on all these commits by considering them as a single unit of work.
2. *repository*: Specifies the Git repository where the *commits* that you want to analyse are located. You need to specify the repository name since an analysis project may contain multiple Git repositories.

Other optional parameters:

* *coupling_threshold_percent*: Specifies minimal temporal coupling for the "Absence of Expected Change" warning. Default is 80 (%).
* *use_biomarkers*: Instructs CodeScene to look for degrading code health, and enables reporting of the quality gates state.

Let's say that we have created an analysis project by specifying a Git remote:

    https://github.com/PHPOffice/PhpSpreadsheet.git

In this case, the *repository* payload parameter is `PhpSpreadsheet` (strip the `.git` extension). If we want to simulate a
delta analysis of the commit designated by the hash `99e5a8e919e1f7b83371a8a586fd6d7875f63583` we issue the following request:

.. code-block:: bash

    curl -X POST -d '{"commits": ["149f9e6"], "repository": "PhpSpreadsheet"}' http://localhost:3003/projects/64/delta-analysis -u 'CodeReview:MyPassword' -H "content-type: application/json"

You can also specify a custom temporal coupling threshold:

.. code-block:: bash

    curl -X POST -d '{"commits": ["149f9e6"], "repository": "PhpSpreadsheet", "coupling_threshold_percent": 50}' http://localhost:3003/projects/64/delta-analysis -u 'CodeReview:MyPassword' -H "content-type: application/json"

Finally, you can enable biomarkers to detect potential code quality problems early:

.. code-block:: bash

    curl -X POST -d '{"commits": ["149f9e6"], "repository": "PhpSpreadsheet", "use_biomarkers": true}' http://localhost:3003/projects/64/delta-analysis -u 'CodeReview:MyPassword' -H "content-type: application/json"


The example assumes that 1) CodeScene runs on localhost and 2) we have configured a user named `CodeReview`.

*Notes to Windows Users*: The curl syntax above won't work on Windows unless you escape the payload properly. We recommend
that you use `Fiddler <http://www.telerik.com/fiddler>`_ instead of curl if you want to test the API on Windows.

Once you've issued the POST request above, CodeScene's Delta Analysis will respond with the following JSON document:

.. code-block:: json

    {"version":"1",
     "url":"/projects/64/delta-analysis/75686456d695d60d99a7cd73302f83606c8a8efc",
     "view":"/64/delta-analysis/view/75686456d695d60d99a7cd73302f83606c8a8efc",
     "result":{"recommended-review-level":"Lightweight sanity check",
               "improvements":["Connector.java improves its code health from 5.6 -> 6.2"],
               "new-files-info": {
                   "summary": "1 new file where the code health is below the threshold for new code, 8.1",
                   "warnings": [
                     {
                       "name": "my-repo\/src\/a_new_file.c",
                       "review": [
                         {
                           "title": "Bumpy Road Ahead",
                           "description": "The code is complex to read due to its nesting with multiple logical blocks. The most complex function is putmsg with 3 logical blocks. A bumpy road like putmsg indicates a lack of encapsulation. Consider to extract smaller, cohesive functions from the bumpy functions.",
                           "indication": 3
                         },
                       ]
                     }
                   ]
                 },
               "quality-gates":{"degrades-in-code-health":true,
                                "violates-goal":false},
               "warnings":[]}}

The parameters in the response carry the following meaning:

* *version*: This is the version of the REST API and will change in future versions of CodeScene.
* *url*: This URL points to the Delta Analysis resource in CodeScene. You can fetch it with an HTTP GET request at any time and it will return the same result document.
* *view*: Points to the page in CodeScene that contains the graphical representation of the result as illustrated in :numref:`deltaanalysisui`.
* *result*: This JSON object contains four fields:
   * *recommended-review-level* is based on the risk profile of the repository, and the riskier the change, the more time we recommend spending on the review.
   * *improvements* is a positive reinforcement that shows code that improves its health.
   * *new-files-info* is an _optional_ field that's included if any new files are introduced in the change set. New content with a low code health fails the quality gate and CodeScene presents the issues.
   * *quality-gates* specifies the state of the two gates that can, optionally, be checked and enforced in the requesting build pipeline.
   * *warnings* specify any early warnings like Complexity Trend increases. In this case it's a low risk commit without any early warning.

Deprecated Fields
~~~~~~~~~~~~~~~~~

The following fields are included in the response, but will be removed from future CodeScene versions:

* *risk*: use the *recommended-review-level* instead.
* *description*: use the *recommended-review-level* instead.

Quality Gates in the REST API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now, let's look at a more complex result. In this case a new developer has made a modification to one of the top Hotspots on a separate
branch. The Delta Analysis reports the following results:

.. code-block:: json

    {"version":"1",
     "url":"/projects/2/delta-analysis/43cc8a146cc0957f2fcb4b09ae3dee71d5a5cf2e",
     "view":"/2/delta-analysis/view/43cc8a146cc0957f2fcb4b09ae3dee71d5a5cf2e",
     "result":{"recommended-review-level":"Detailed: the change is high risk as it is a more wide-spread
                                           change than 98% of all your commits.
                                           The risk increases as the author has somewhat lower
                                           experience in this repository.",
               "improvements":[],
               "quality-gates":{"degrades-in-code-health":false,
                                "violates-goal":false},
               "warnings":[
                 {"category":"Modifies Hotspot",
                  "details":["mvc/src/Microsoft.AspNetCore.Mvc.TagHelpers/LinkTagHelper.cs"]},
                 {"category":"Absence of Expected Change Pattern",
                  "details":["mvc/src/Microsoft.AspNetCore.Mvc.TagHelpers/ScriptTagHelper.cs"]}]}}

We see that CodeScene recommends a detailed review due to the increased defect risk.
We also note that CodeScene calls our attention to the modified Hotspot. We use this information  to review the change more carefully. Finally we note that CodeScene detects the absence of an expected
change pattern. In this codebase, the `LinkTagHelper.cs` is usually changed together with the `ScriptTagHelper.cs` file. Since that
wasn't the case here, CodeScene informs us about the omission so that we can investigate it and catch a potential bug early.

Finally, let's see how a failed code quality gate looks:

.. code-block:: json

    {"version":"1",
     "url":"/projects/2/delta-analysis/43cc8a146cc0957f2fcb4b09ae3dee71d5a5cf2e",
     "view":"/2/delta-analysis/view/43cc8a146cc0957f2fcb4b09ae3dee71d5a5cf2e",
     "result":{"recommended-review-level":"Lightweight sanity check",
               "improvements":[],
               "quality-gates":{"degrades-in-code-health":true,
                                "violates-goal":true},
               "code-owners-for-quality-gates":["@TheTester" "@TheMicroManager"],
               "warnings":[
                 {"category":"Degrades in Code Health",
                  "details":["ViewComponentResultTest.cs degrades from a Code Health of 10.0 -> 9.0"
                             "ControllerActionInvokerTest.cs degrades from a Code Health of 5.0 -> 4.7"]},
                 {"category":"Violates Goals",
                  "details": ["Hotspots marked supervise, ControllerActionInvokerTest.cs, degrades from a Code Health of 5.0 -> 4.67"]}]}}

The failed quality gates are indicated in the `quality-gates` field. We also note that CodeScene includes the
`code-owners-for-quality-gates` field, which specifies the two owners -- as read from a `CODEOWNERS` file -- that are responsible for
the code that failed the quality gates.

Delta Analysis in Offline Mode
------------------------------

Delta analysis is triggered via an API call and thus requires authentication.
Since CodeScene checks the license on a remote license server with every authentication request,
the delta analysis API call will fail if CodeScene can't reach the license server.
If you don't have an Internet connection or you don't want to let CodeScene access the Internet,
you need to specify `offline-mode` parameter:

.. code-block:: bash

    curl -X POST -d '{"commits": ["149f9e6"], "repository": "PhpSpreadsheet"}' http://localhost:3003/projects/64/delta-analysis?offline-mode=offline -u 'CodeReview:MyPassword' -H "content-type: application/json"

Please note that there is a new `offline-mode=offline` parameter in the query string.

If you always run CodeScene in offline mode, you can also turn on `Global Offline Mode`
in the configuration. With global offline mode, you don't have to append `offline-mode=offline` parameter
to your delta analysis API URLs.

Read more about the limitations and usage in :ref:`offline-mode` documentation.
