Expand on details

Author: olafurpg

blog/_posts/2017-02-23-scalafix-v0.3.md

@@ -1,32 +1,72 @@
-# Refactor with scalafix
+---
+layout: blog
+post-type: blog
+by: Ólafur Páll Geirsson
+title: "Refactor with scalafix v0.3"
+---
 
-We are happy to announce the release of [scalafix v0.3][scalafix].
-This release introduces a new `Rewrite` and `Patch` API powered by the [scala.meta semantic API][meta-1.6].
-We are excited about this release because we believe it enables a number promising tooling applications.
+I am happy to announce the release of [scalafix v0.3][scalafix].
+This release leverages the new scala.meta semantic API to provide a re-designed `Rewrite` and `Patch` API for refactorings.
+Let me explain what that means word by word.
 
-Scala.meta recently had its first release of its semantic API; the semantic API provides operations to query information from the compiler.
-This has enabled rewrites in scalafix to query for the so-called "symbol" of a name that appears in a Scala source file.
+## scala.meta semantic API
+
+Scala.meta recently announced the [first release of its semantic API][meta-1.6].
+This release is the product of close collaboration for the past several months between
+[@xeno-by](https://twitter.com/xeno_by) at Twitter and myself at the Scala Center.
+The semantic API provides operations to query information from the compiler.
+
+The first version of the scala.meta semantic API makes it possible to query for the "symbol" of a name that appears in a Scala source file.
 A symbol is a unique identifier of a definition such as a class, val, def or trait.
-This ability to query for symbols opens possibilities for a great number of refactorings including imports management and identifier renaming.
+For example, the symbol of `println` from the standard library is `_root_.scala.Predef.println(Ljava/lang/Object;)V`.
 
-The long-term mission of scalafix is to help automate the migration of deprecated Scala 2.x features to Dotty.
-However, scalafix can be used for more than migrating between Scala versions; it can also be used for ad-hoc library and application migrations.
-To demonstrate what rewrites can be implemented with scalafix v0.3, let's step through an example of a real usecase.
+Symbols are created by "scalahost", a compiler plugin.
+Scalahost emits symbols of a source file in the form of a "semantic database".
+The semantic database can be persisted to files on disk and loaded for later analysis.
+Semantic databases from different compilation units, potentially produced by different
+versions of the Scala compiler, can be merged.
+This opens possibilities for large-scale code analysis.
+
+The introduction of the scala.meta semantic API is a game changer for scalafix.
+The ability to query for symbols open possibilities for many scalafix rewrites.
+
+## Rewrite: meta.Tree => Seq[Patch]
+
+A scalafix `Patch` is a small operation that can produce a diff on a Scala source file.
+A patch can either be a "token patch" or a "tree patch".
+
+Token patches are low-level but give full control of how small details are handled in a source files, for example formatting and comments 
+Example token patches are `Remove(token)` and `AddLeft(token, toAdd: String)`, which removes or prepends a string to `token`, respectively.
+
+Tree patches are high-level and allow rewrite author to declaratively explain what operation to perform.
+An example tree patch is `AddGlobalImport(importer)`, which adds a new import to the top of a file if it does not exist.
+Observe that `AddGlobalImport` does not worry about token-level details such as whether the user groups imports by prefix (e.g., `import a.{b, c}`).
+
+Tree and token patches build a small algebra of operations that can be composed to build complex refactorings.
+A challenge with composing patches is to figure out what to do on conflicts.
+For example, what happens when one patch renames a token while the other patch removes the same token?
+The current strategy in scalafix is to try and resolve as many conflicts as possible on the tree patch level.
+Once we we only have token patches, it is harder to resolve conflicts.
+Unsolvable conflicts on the token level abort the refactoring.
+In the future, we hope to support more advanced conflict resolution strategies.
+
+In a nutshell, a scalafix `Rewrite` is a `scala.meta.Tree => Seq[Patch]` function.
+The tree is backed by the scala.meta semantic API, so the rewrite is able to query for compiler information such as symbols.
+To demonstrate how rewrites are implemented with scalafix v0.3, let's step through an example use-case.
 
 ## Example: Xor to Either
 
 The functional programming library [cats][cats] migrated recently from its `Xor` data type to `Either` from the standard library.
 It requires a few mechanical steps to migrate code to use `Either` instead of `Xor`.
-For example, below is a diff that's taken from [circe][xor-cire]'s migration to `Either`.
+For example, below is a diff that's taken from [circe][xor-circe]'s migration to `Either`.
 
 ```diff
--  final def either: Xor[HCursor, HCursor] = if (succeeded) Xor.right(any) else Xor.left(any)
-+  final def either: Either[HCursor, HCursor] = if (succeeded) Right(any) else Left(any)
+-final def either: Xor[HCursor, HCursor] = if (succeeded) Xor.right(any) else Xor.left(any)
++final def either: Either[HCursor, HCursor] = if (succeeded) Right(any) else Left(any)
 ```
 
-Scalafix rewrites are composed of so-called "patches".
-A patch describes a single refactoring operation.
-`Replace` is one patch that can be used to rename identifiers
+For this particular rewrite, we are able to get away with only using tree patches.
+`Replace` is one tree patch that can be used to replace usage of a reference such as a type, term or a static method.
 
 ```scala
 Replace(Symbol("_root_.cats.data.Xor."), q"Either")
@@ -37,7 +77,10 @@ Replace(Symbol("_root_.cats.data.Xor.Right."), q"Right")
 The `Symbol(_root_...data.Xor)` part is the scala.meta symbol referencing the class definition of `cats.data.Xor`.
 As we saw in the `either: Xor[HCursor` diff above, references to `Xor` should become `Either` after the rewrite.
 
-To introduce new imports on rename, it's possible to pass in `additionalImports`
+Symbols are normalized by default, so the `cats.data.Xor.Right` replace patch will handle the `Xor.Right` type, `Xor.Right` companion object as well as the `Right.apply` constructor method.
+
+To introduce new imports, it's possible to pass in `additionalImports`
+
 ```scala
 Replace(Symbol("_root_.cats.data.XorT."), q"EitherT",
         additionalImports = List(importer"cats.data.EitherT")),
@@ -48,20 +91,40 @@ Imports can be removed with the `RemoveGlobalImport` patch
 ```scala
 RemoveGlobalImport(importer"cats.data.Xor")
 ```
+
 Nothing happens if the import does not appear in the source file.
 Likewise, it's OK to add the same import twice, scalafix will de-duplicate it.
 
 The full `Xor` to `Either` scalafix rewrite can be found [here][xor2either] and its accompanying test
 suite [here][xor2either-test].
 
-To learn more about how to start with scalafix, visit the [installation docs][install]!
+## Try it out!
+You can use scalafix both as a library and a tool.
+
+The recommended way to use scalafix as a library is with the [`sbt-scalahost`][sbt-scalahost] plugin.
+By using scalafix as a library, you have full control of how, where and when to run rewrites.
+
+The recommended way to use scalafix as tool is the [`sbt-scalafix`][sbt-scalafix] plugin.
+It's possible define custom tree patches in the [`.scalafix.conf` configuration file][config-patches].
+
+The long-term mission of scalafix is to help automate the migration of deprecated Scala 2.x features to Dotty.
+However, as I have hopefully demonstrated in this post, scalafix can be used for more than just migrating between Scala versions.
+Scalafix can also be used for ad-hoc library and application migrations.
 
-## Cross-building
+I am excited to see what applications the community can build with scala.meta and scalafix.
+Some promising ideas that have floated around include
 
-TODO: Shane
+- parse and run rewrites from `@deprecated` warning messages. This would enable library authors
+  to provide exectuable migration guides.
+- use scalafix to cross-build against multiple similar APIs. For example, a
+  library author could write against scalaz and rewrite to cats.
+- build a code search web-interface with "jump to definition" functionality
+  powered by the scala.meta's semantic database.
+- replace usage of the infamous `any2StringAdd` in favor of string interpolators or explicit `.toString`.
+- replace usages of `scala.Seq`, which can be mutable, in favor of `scala.collection.immutable.Seq`.
 
-## Custom rewrites
-You can write your own custom rewrites.
+If this sounds exciting to you, join us!
+I am happy to answer any question in the [scalafix gitter][gitter] channel.
 
 [xor2either-test]: https://github.com/scalacenter/scalafix/blob/f61136fad79afcdbb03528ce78c7928afc6eafd6/scalafix-nsc/src/test/resources/syntactic/Xor2Either.source
 [xor2either]: https://github.com/scalacenter/scalafix/blob/f61136fad79afcdbb03528ce78c7928afc6eafd6/core/src/main/scala/scalafix/rewrite/Xor2Either.scala
@@ -70,5 +133,9 @@ You can write your own custom rewrites.
 [ghpages]: http://github.com/scalacenter/scalafix
 [prevpost]: http://scala-lang.org/blog/2016/10/24/scalafix.html
 [scalafix]: https://scalacenter.github.io/scalafix/#0.3.0
+[sbt-scalafix]: https://scalacenter.github.io/scalafix/#sbt-scalafix
+[sbt-scalahost]: https://scalacenter.github.io/scalafix/#sbt-scalahost
 [install]: https://scalacenter.github.io/scalafix/#Installation
 [meta-1.6]: https://github.com/scalameta/scalameta/blob/master/changelog/1.6.0.md#semantic-api
+[config-patches]: https://scalacenter.github.io/scalafix/#patches
+[gitter]: https://gitter.im/scalacenter/scalafix