Build code analyzers with Scalameta and Scalafix

Friday 16 November 2018

Ólafur Páll Geirsson, Eugene Burmako

BLOG

We are excited to announce the release of Scalameta v4.0.0 and Scalafix v0.9.0 introducing new APIs enabling more advanced source code analysis. Scalameta is a library to read, analyze, transform and generate Scala programs. Scalafix is a refactoring and linting tool.

This release is the result of a close collaboration between the Scala Center and Twitter along with contributions from over 30 contributors in the community. Big thanks to everybody who made this happen!

In this post, we cover some exciting aspects of this release.

  • new documentation for getting started with Scalameta and Scalafix
  • the ability to query information about Scala and Java symbols on the classpath.
  • the ability to inspect synthetics generated by the compiler such as inferred type parameters and implicits.
  • how the community is sharing Scalafix rules for linting code and migrating between library versions.

Get started with the new documentation

A big focus of this release has been documentation. Scalameta and Scalafix have new websites with guides, cookbooks and reference documents.

Visit scalameta.org to see the new Scalameta documentation. Key pages of the site include:

  • SemanticDB specification: learn the details of the new semantic API.
  • SemanticDB guide: get started with the SemanticDB command-line tools metac, metacp and metap.
  • Trees guide: learn how to parse, construct, traverse and transform Scala syntax trees.
  • ScalaFiddle playground: explore Scalameta APIs directly in the browser with access to code completions and fast edit/compile/run feedback. Big thanks to scalafiddle.io for providing a great service!

Visit scalacenter.github.io/scalafix to see the new Scalafix documentation. Key pages of the site include:

We hope the new documentation helps more people join the effort in building developer tools for Scala.

Query information about Scala and Java symbols

A highlight of this release is the new ability to query information about Scala and Java symbols on the classpath. Symbol information includes the symbol’s kind (class/trait/object), properties (final/implicit/sealed), signature (method parameters/class declarations), annotations (@inline) and access modifiers (private/protected).

In Scalameta, symbol information is documented in the SemanticDB specification. SemanticDB is a data model for semantic information such as symbols and types about programs in Scala and Java. SemanticDB decouples production and consumption of semantic information, establishing documented means for communication between tools.

The SemanticDB specification contains dedicated sections for Scala symbols and Java symbols with relevant hyperlinks to respective language specifications. The SemanticDB specification also contains detailed code examples illustrating how Scala and Java language features map into SemanticDB data structures.

In Scalafix, there is a library API to query information about SemanticDB symbols. The SymbolInformation cookbook includes small recipes for how to perform a range of tasks such as listing the parameters of a method or finding all supertypes of a class.

Inspect inferred implicits and inferred type parameters

A new feature in this release is Synthetic, a data structure that encodes trees that do not appear in the original source code but are added by the compiler. Examples of synthetics include inferred type parameters, implicit arguments, or desugarings of for comprehensions.

In Scalameta, synthetics are documented in the SemanticDB specification. In Scalafix, there is a library API to inspect synthetics via the .synthetic extension method. For example, the code Some(1) has a synthetic *.apply[Int] where * represents the original Some tree node and apply resolves to the symbol scala/Option.apply().. Consult the new SemanticTree docs to learn more about using synthetics in the Scalafix API.

Synthetics were contributed by Max Ovsiankin during his internship at Twitter this summer. Max did a great job and synthetics represent only a fraction of his contributions this summer.

Share your code analyzer

A new functionality in this release is the ability to easily install and run custom Scalafix rules. For sbt users, custom rules can be installed with the scalafixDependencies setting and discovered from the sbt shell via tab completions.

// build.sbt
scalafixDependencies in ThisBuild += "org.http4s" %% "http4s-scalafix" % "0.20.0-M3"

sbt shell tab completion for Scalafix rules

For rule authors, a Scalafix rule is published to Maven Central as an ordinary library.

Within a day after the Scalafix release, Eugene Yokota had already published a Scalafix rule NoInfer.

Julien Tournay has also shared Scalafix migration rewrites for Scio v0.7, a Scala library from Spotify for Apache Beam and Google Cloud Dataflow.

Alessandro Marrella also contributed migration rewrites for http4s, a typeful, functional, streaming HTTP library for Scala.

We hope that Scalafix rules will help reduce the pain when upgrading library dependencies with breaking changes.