Dialyzer is a static analysis tool for Erlang that identifies software discrepancies, such as definite type errors, code that has become dead or unreachable because of programming errors, and unnecessary tests, in single Erlang modules or entire (sets of) applications.

Dialyzer is integrated with rebar3 (a build tool for Erlang), and its default output looks like this:

This is a good starting point, but it's not very useful in some cases:

1. If you have lots of warnings, this output covers several screens, and it becomes difficult to parse through everything.
2. If you run this in some sort of continuous integration (like Jenkins), then the console output is not very friendly.

One way to improve this is to generate an HTML report which can be published/emailed/opened in the browser.

So, I build a rebar3 plugin that generates a nicely formatted color HTML report from the dialyzer output. The plugin can be found on hex.pm, or on github.

Usage

Make sure you're using rebar3 version 3.15 or later.

1. Add the plugin to your rebar.config:

{plugins, [
    %% from hex
    {rebar3_dialyzer_html, "0.2.0"}
    
    %% or, latest from git
    {rebar3_dialyzer_html, {git, "https://github.com/srijan/rebar3_dialyzer_html.git", {branch, "main"}}}
]}.

2. Select raw format for the dialyzer warnings file generated by rebar3 (this is a new flag available from rebar 3.15):

{dialyzer, [
    {output_format, raw}
]}.

3. Run the dialyzer_html rebar3 command:

$ rebar3 dialyzer_html          
===> Generating Dialyzer HTML Report
===> HTML Report written to _build/default/dialyzer_report.html

Here's how the report looks:

How I built the plugin

rebar3 dialyzer

The rebar3 built-in dialyzer plugin does the following:

1. Runs dialyzer with the options configured in rebar.config
2. Converts the output to ANSI color format and write it to console (it has a custom function for this formatting)
3. Converts the output to basic format (using built-in dialyzer:format/2) and write it to a dialyzer_warnings file.

I wanted to find out the easiest way to get a nicely formatted HTML report, ideally without forking the rebar3 project itself.

The first thing I needed was a way to save the raw (machine parse-able) dialyzer output to the warnings file instead of the default formatted output. For this, I submitted a new feature to the rebar3 project, and it introduces a new config to enable this. So, this plugin needs rebar3 version 3.15 or later.

Plugin vs Escript

Next, to actually parse and output the HTML file, I would need to run some Erlang code. There are two options I considered:

1. Escript called from Makefile/wrapper
   This option works okay, but we cannot re-use any rebar3 internal function or State. I wanted to use rebar3's own custom function for formatting the dialyzer warnings, so decided to not go with this option.
   
2. Custom rebar3 plugin
   Doing it this way makes it easy for anyone to use, and I can re-use things already implemented in rebar3 itself. So, I decided to use this option.
   

HTML output

Now, in the custom rebar3 plugin, I needed to convert the ANSI color-coded output given by rebar_dialyzer_format:format_warnings/2 into something for HTML.

I thought of the following options:

1. rebar3 uses the cf library to convert tagged strings to ANSI color codes. I can use something like dependency injection to replace the cf module with my own module so that the tagged strings are directly converted to HTML without even going to the intermediate ANSI color-coded format.
   
   This method seemed very hacky, so I decided not to pursue it. But, if rebar3 makes the dialyzer format interface configurable, I can reevaluate this approach.
   
2. Convert by writing a library in Erlang for ANSI code to HTML tags conversion.
   There is a library called ansi_to_html in elixir - but didn't want to add a huge dependency like that.
   But writing a new Erlang library to do this can be a future optimization.
   
3. Convert using a JS library after page load. I found a javascript library called ansi_up which can convert ANSI codes to HTML color tags, or it can add CSS classes that can be styled as required.
   

I opted for approach #3 because it was the easiest. I also grouped the warnings by app name so that all warnings for a single app are in one place, and the report includes the number of warnings per app.

Also, if the JS library could not be loaded (for example due to no internet, or any security headers), then it will still show the basic formatted output using dialyzer:format/2.

Future Improvements

1. I want to remove the dependency on Javascript, and want to write/use a pure Erlang library that can convert the ANSI codes to HTML.
2. Ideally, rebar3 itself can separate the dialyzer warning parsing and formatting into different functions, and make it possible to override the formatting function so that any plugin can pass its own formatting function into the dialyzer plugin.
3. This can even run git commands in the shell to figure out if any lines changed in the most recent commit involve a warning, and maybe highlight them especially in the report. This can be useful CI reports on pull requests.
4. Maybe make the format plug-able so the report can be saved in any JSON / XML or any custom format.

Let me know in the comments below, or on twitter/github if you have any suggestions for this plugin.

At work, we use the multi-app project pattern to organize our codebase. This lets us track everything in a single repository but still keep things isolated.

For isolation, we wanted to restrict apps to only be able to call the public interfaces of other apps (similar to facade pattern). However, since everything in Erlang is in a global namespace, nothing prevents code in one app to call the (exported) functions from another app.

Next best solution—detect the above scenario and raise warnings during code review/CI.

Xref to the rescue:

Xref is a cross reference tool that can be used for finding dependencies between functions, modules, applications and releases.

Xref includes some predefined analysis patterns that perform some common tasks like searching for undefined functions, deprecated function calls, unused exported functions, etc.

How it works: when xref server is started and some modules/applications/releases are added for analysis, it builds a Call Graph: a directed graph data structure containing the calls between functions, modules, applications or releases. It also creates an Inter Call Graph which holds information about indirect calls (chain of calls). It exposes a very powerful query language, which can be used to extract any information we want from the above graph data structures.

To demonstrate this, I created a sample multi-app repository: library_sample. There are some cross-app function calls in this code that we want to detect.

This repo is supposed to represent the functionality of a physical Library. It has four apps: library, library_api, library_catalog, and library_inventory. library_catalog has metadata about the books in the library, library_inventory has information about the availability of books, return dates, etc., library_api has HTTP handlers which call the above, and library is the main app which brings it all together.

Let’s say we want that library_api can call library_catalog and library_inventory functions, but catalog and inventory cannot call each other directly.

First, we clone the repo and run rebar3 shell:

$ git clone https://github.com/srijan/library_sample
Cloning into 'library_sample'...
remote: Enumerating objects: 29, done.
remote: Counting objects: 100% (29/29), done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 29 (delta 3), reused 29 (delta 3), pack-reused 0
Unpacking objects: 100% (29/29), 910.62 KiB | 2.53 MiB/s, done.

$ cd library_sample

$ ./rebar3 shell
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling library_inventory
===> Compiling library_catalog
===> Compiling library
===> Compiling library_api
Erlang/OTP 23 [erts-11.1.7] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Eshell V11.1.7  (abort with ^G)
1>

Then, we start xref and add our build directory for analysis:

1> xref:start(s).
{ok,<0.185.0>}

2> xref:add_directory(s, "_build/default/lib", [{recurse, true}]).
{ok,[library_api,library_app,library_catalog,
     library_inventory,library_sample_app,library_sample_sup,
     library_sup]}

Using xref:q/2 for querying the constructed call graph:

3> xref:q(s, "E | library_inventory || library_catalog").
{ok,[]}

4> xref:q(s, "E | library_catalog || library_inventory").
{ok,[{{library_catalog,get_by_id,1},
      {library_inventory,get_available_copies,1}}]}

This means that there are no direct calls from the library_inventory application to the library_catalog application. But, there is a direct call from library_catalog:get_by_id/1 to library_inventory:get_available_copies/1.

The query E | library_catalog || library_inventory can be read as:

• E = All Call Graph Edges
• | = The subset of calls from any of the vertices. So | library_catalog creates a subset which contains calls from the library_catalog app.
• || = The subset of calls to any of the vertices. So, || library_inventory further creates a subset of the previous subset which contains calls to the library_inventory app.

To get both direct and indirect calls, closure E has to be used:

5> xref:q(s, "closure E | library_catalog || library_inventory").
{ok,[{{library_catalog,get_by_id,1},
      {library_inventory,get_all,0}},
     {{library_catalog,get_by_id,1},
      {library_inventory,get_available_copies,1}}]}

This tells us that there is an indirect direct call from library_catalog:get_by_id/1 to library_inventory:get_all/0.

The query language is very powerful, and there are more interesting examples in the xref user’s guide.

But this only runs the required queries manually in Erlang shell. We want to be able to run it in continuous integration. Luckily, rebar3 comes with a way to specify custom xref queries to run when running ./rebar3 xref, and to raise an error if they don’t match against the expected value defined.

Here’s the xref section from my rebar.config:

{xref_queries, [
                {"closure E | library_catalog || library_inventory", []},
                {"closure E | library_inventory || library_catalog", []}
               ]}.

This performs the two queries I want and matches them against the the target value of []. Sample output:

$ ./rebar3 xref
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling library_inventory
===> Compiling library_catalog
===> Compiling library
===> Compiling library_api
===> Running cross reference analysis...
===> Query closure E | library_catalog || library_inventory
 answer []
 did not match [{{library_catalog,get_by_id,1},{library_inventory,get_all,0}},
                {{library_catalog,get_by_id,1},
                 {library_inventory,get_available_copies,1}}]

So, now this is ready for automation.