*****************
Viewing Results
*****************

.. container:: PRELUDE BEGIN

.. container:: PRELUDE ROLES

.. role:: ada(code)
    :language: Ada

.. role:: C(code)
    :language: C

.. role:: cpp(code)
    :language: C++

.. role:: rust(code)
    :language: Rust

.. container:: PRELUDE SYMBOLS

.. |rightarrow| replace:: :math:`\rightarrow`
.. |forall| replace:: :math:`\forall`
.. |exists| replace:: :math:`\exists`
.. |equivalent| replace:: :math:`\iff`
.. |le| replace:: :math:`\le`
.. |ge| replace:: :math:`\ge`
.. |lt| replace:: :math:`<`
.. |gt| replace:: :math:`>`
.. |checkmark| replace:: :math:`\checkmark`

.. container:: PRELUDE END

================
Report Command
================

---------------------
Generating a Report
---------------------

+ To view results, you must generate a **report**

  + From the command line

    :command:`gnatsas report -Psdc.gpr`

    | *Default output format (text), written to standard output*
    |
    |

    :command:`gnatsas report csv -Psdc.gpr --out report.csv`

    | *Generate a comma-separated values file, save in* :filename:`report.csv`

--------------------------
Available Output Formats
--------------------------

text
   Compiler-like listing of messages

html
   HTML output generated by :toolname:`gnathub`. Output always stored in :filename:`index.html` in :filename:`gnathub/html-report` subfolder of object directory

csv
   Comma-separated values, useful for input into third-party tools like spreadsheets

security
   HTML report focusing on certain vulnerabilities

code-climate
   JSON output useful with tools such as BitBucket and Gitlab

sarif
   Output for integration with any SARIF viewer tool

exit-code
   Number of messages (up to 255) will be returned as the report exit code. Useful for automation processes

For more information, refer to *GNAT SAS User's Guide Section 5.4 - Report Formats in Detail*

------------------------------
Selecting Results to Display
------------------------------

* :command:`gnatsas report` always displays results of last run (regardless of run's switches)

* To generate report for other runs

  * Specify a timeline

    :command:`gnatsas report text -P sdc.gpr --timeline <timeline>`

  * Specify a SAM file

    :command:`gnatsas report text <sam-file>`

---------------
Message Kinds
---------------

* Message kinds fall into one of the following categories

  * Warning - compilation warnings issued by GNAT front end
  * Check - possible runtime check failures
  * Informational - extra information about a message
  * Race Condition - messages about synchronization objects
  * Annotation - Information about a subprogram determined by analysis

* Each of these categories has multiple messages

  * :toolname:`GNAT SAS` reporting can call out message kinds by category or individual kind

See section *10 GNAT SAS Messages Reference* of the documentation for more detailed information

--------------------
Message Categories
--------------------

Messages can be grouped by *category*. These categories can be used to determine which messages are displayed in the report.

.. container:: latex_environment tiny

  .. list-table::

    * - **Age**

      - Compared to the previous run, is this message the same, new, or no longer there

    * - **Kind**

      - Kind of message (category (e.g. ``check``) or kind (e.g. ``range_check``)

    * - **Rank**

      - Severity - likelihood that message identifies a defect that could lead to incorrect results

    * - **Tool**

      - Which analysis engine generated the message

    * - **CWE**

      - *Common Weakness Enumeration*

    * - **Review Status**

      - Actual status of message review (see section on *Message Review*)

    * - **Review Kind**

      - Category of review status (see section on *Message Review*)

    * - **Project**

      - Project containing source file with the message

    * - **File**

      - Specific file containing message

--------------------------------
Filtering Messages by Category
--------------------------------

* Use :command:`show` switch to add or remove messages from report

   :command:`gnatsas report --show [category_constraint]*`

   where *category_constraint* can be specified as

.. container:: latex_environment footnotesize

  .. list-table::

    * - ``<category>=<constraint>``

      - Restrict report to messages that match constraint

    * - ``<category>+<constraint>``

      - Add to report messages that match constraint

    * - ``<category>-<constraint>``

      - Remove from report messages that match constraint

---------------------------------------------
Switches for Filtering Messages by Category
---------------------------------------------

:command:`gnatsas report -P sdc.gpr --show <filter=value>`

.. container:: latex_environment footnotesize

  .. list-table::
    :header-rows: 1

    * - Filter

      - Value Choices

    * - ``default``

      - Default categories with constraints

    * - ``all``

      - Only specified categories with constraints

    * - ``age``

      - unchanged, added, removed

    * - ``kind``

      - Message kind (category or individual kind)

    * - ``rank``

      - info, low, medium, high

    * - ``tool``

      - inspector, infer, gnatcheck, gnat

    * - ``cwe``

      - Specific CWE or "none"

    * - ``review_status``

      - Any review statuses or "none"

    * - ``review_kind``

      - not_a_bug, pending, bug, uncategorized, none

    * - ``prj``

      - runtime or project base name, or relative paths

    * - ``file``

      - Source filename basename or relative path

*Note:* **none** matches those messages that do not have corresponding information attached (e.g., no CWE or no review)

=========================
Comparing GNAT SAS Runs
=========================

--------------------
Using History Data
--------------------

* :dfn:`Baseline run` is first run performed at appropriate mode

  * *fast* and *deep* have different baselines

* Report indicates if message is *new*, *unchanged*, or *removed* relative to baseline

* Can change baseline with :command:`gnatsas baseline` command:

  * :command:`bump-baseline` switch sets last analysis run as a baseline
  * :command:`set-baseline <sam-file>` switch sets specified SAM file to be the baseline

* To compare different runs without updating baseline, use :command:`gnatsas report --compare-with <sam-file>`

  * Current run will be compared to specified run without impacting baseline

-----------------------------
Classifying Message Changes
-----------------------------

* In determining if message is *unchanged*, *added*, or *removed* even when surrounding source changes, :toolname:`GNAT SAS` checks for:

  * Full name of procedure where message was generated
  * Analysis engine that emitted message
  * Kind of message
  * Selected content within the message (depending on kind)

* If all the above matches multiple messages, :toolname:`GNAT SAS` uses order of appearance in code

*Note: default behavior is to not mention removed messages and to call out specifically new messages*

=============
GUI Reports
=============

---------------------------------
Viewing Reports Via GNAT Studio
---------------------------------

* To view report from within :toolname:`GNAT Studio`

  * Perform analyis (:menu:`GNATSAS` |rightarrow| :menu:`Analyze All`) 

    * Report appears when analysis completes

  * :menu:`GNATSAS` |rightarrow| :menu:`Display Code Review`

    * Will open report if analysis has ever been done

  * :menu:`GNATSAS` |rightarrow| :menu:`Advanced` |rightarrow| :menu:`Regenerate Report`

    * Brings up dialog for report generation
    * Allows user to specify options such as :command:`compare-with` or :command:`show`

-----------------------------
GNAT Studio Analysis Report
-----------------------------

.. image:: gnatsas/sas_report_annotated.png
  :width: 80%

* Baseline / Current run SAM file

  * Hover over these filenames gives switches used in run

* Filters

  * Control which messages appear in report table/locations view

* Locations View

  * Click on any message to go to appropriate source line
  * Click on pencil icon to add review/annotion


