#+title: Annotator - an interactive Coverity annotation tool

* Abstract

This tool lets you interactively annotate your code given a =defects.err= file. The file should contain file and line information along with the Coverity rule that was violated. An example may look like this:

#+begin_example csv
main.cpp:162:INFO: Newest, autosar_cpp14_a20_8_6_violation: Object "std::unique_ptr<Configuration const, std::default_delete<Configuration const> >(read_configuration(uri))" is not constructed using "std::make_shared".
#+end_example

* Installation

Get the most recent release, unpack it and add the binary to your PATH.

* Usage

After a /Coverity™/ run, you end up with a =defects.err= and would like to
annotate your code accordingly. In order to do so, just execute the =annotator=:

#+begin_src sh
annotator
#+end_src

This will by default use the =defects.err= file in the current directory and
scan it for violations. It will then ask you what to do with each violation - by
default only /Newest/ violations will be handled, but this can be overridden
with a command-line switch.

After all violations have been treated, you'll end up with a bunch of =*.fix=
files next to each source file - those are the annotated source files - you may
run diff on them to check if they look fine or just move them over your original
source file.

** Possible annotations

The annotator is able to generate three kinds of annotations:

- Intentional :: by pressing =i=, this will annotate with =coverity[rule] <reason>=
- FalsePositive :: by pressing =f=, this will annotate with =coverity[rule : FALSE] <reason>=
- Todo :: by pressing =t=, this will annotate with a TODO marker

* Advanced usage scenarios

The current annotator supports the following command-line arguments:

#+name: annotator-help
#+begin_src sh :results output :exports both
annotator --help
#+end_src

#+RESULTS: annotator-help
#+begin_example
Usage: annotator [OPTIONS] files...

A tool to semi-automatically add Coverity source-code annotations based on found defects.


  -v         --verbose             be more verbose, pass multiple times to increase verbosity
  -i         --inplace             replace source-file after inserting annotations
  -V         --version             show full version information
             --short-version       show just the version number
  -h         --help                show usage information
  -b         --batch               run in batch mode, i.e. do not ask any questions
  -a         --all                 handle all defects not just Newest
  -C[NUM]    --context[=NUM]       specify how much context should be shown around a violation
  -t STRING  --todo-marker=STRING  override the default TODO marker with a custom string
  -A FILE    --annotations=FILE    load automatic annotation rules
                                     some examples:
                                        Intentional (Rule "rule_1") "some reason"
                                        FalsePositive (Rule "rule_1") "some reason"
                                        ToDo (Rule "rule_1")
                                        # a comment
                                        -- another comment
#+end_example

** In-place annotations

The =annotator= allows to annotate in-place, i.e. it will automatically rename the =.fix= file after you are done with all violations within that file. This can be achieved by passing =-i= or =--inplace=.

** Process all violations

By default the annotator will only handle *Newest* violations and not those that are already contained within the Coverity database for some reason. However, it's still possible to process all found violations by passing =-a= or =--all= on the command-line.

** Insert annotations automatically

In case you have violations that always result in the same annotation over and over again, you can supply one or more files that contain automatic decisions.

Each line may be one of the following:

#+begin_example haskell
Intentional (Rule "autosar_cpp14_a18_9_1") "reason why it's intentional"
FalsePositive (Rule "autosar_cpp14_a18_9_1") "reason why it's a false-positive"
ToDo (Rule "autosar_cpp14_a18_9_1")
#+end_example

Lines may be disabled by prefixing them with =#= or =--=.