[refactor] Initial support for refactoring action rules

[arphaman]

Summary

This patch implements a couple of functions that were described in my RFC from last week that’s available at http://lists.llvm.org/pipermail/cfe-dev/2017-July/054831.html. This patch adds the following pieces: apply function, requiredSelection function, and the selection::SourceSelectionRange constraint.

This code will be used as a base to start moving the functionality and tests for clang-rename over to clang-refactor.

[arphaman]

• Simplify error/diagnostic handling. Use DiagnosticOr instead of DiagOr<Expected>.
• Simplify the code for the selection requirements by removing lambda deducers and instead using special classes for requirements instead of lambdas/functions.
• Rename selectionRequirement to requiredSelection

[arphaman]

+ Introduce refactoring diagnostics.

[arphaman]

Ping.

[ioeric]

This is great work and definitely a lot to digest! ;) Some high-level comments for the first round.

In general, I really appreciate the high-level interfaces; I am just a bit concerned about the implementation which is a bit hard to follow at this point, especially with all the template magics. I left some suggestions in the comments; hopefully they would help.

I would also appreciate more detailed high-level comments on the major classes and their relationships - I found myself constantly going back to the RFC to understand their intentions.

include/clang/Basic/DiagnosticOr.h

1

Could you please split changes related to DiagnosticOr into a separate patch and have owners of clang/Basic/ directory review it? ;)

include/clang/Tooling/Refactoring/RefactoringActionRules.h

1

Code in this file is a bit hard to follow, especially with so many classes and template magics :P

Is it possible to split them into smaller modules, and ideally with more detailed documentation for each?

It seems to me that the following logics could live in their own headers:

• RefactoringActionRule interface.
• Base classes for requirements.
• SourceSlection-related requirements.
• Derived/specialized rules.

227

Why is this called apply? I feel something like createAction or generateAction would be more intuitive.

include/clang/Tooling/Refactoring/RefactoringOperationController.h

19

What are all the possible states, for example?

22

Maybe I am missing too much context, but I found it hard to understand the comment and couldn't relate the comment to the public interfaces. Could you elaborate more?

It is also unclear to me if this is specific to the source selection.

40

It's unclear to me what the intentions of these members are. Could you add some comments for these members?

include/clang/Tooling/Refactoring/RefactoringResult.h

35

Do we expect the result changes to be modified? Why?

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

21

nit: redundant be used.

35

It might worth explaining the relationship between this and the RequirementBase.

[alexander-shaposhnikov]

include/clang/Basic/DiagnosticOr.h

40

explicit ?

49

but probably it would be a bit cleaner to enable SFINAE via a template parameter (http://en.cppreference.com/w/cpp/types/enable_if , option #4) rather than via extra argument.

include/clang/Tooling/Refactoring/RefactoringResult.h

27

explicit ?

[arphaman]

Extracted DiagnosticOr to a separate patch at https://reviews.llvm.org/D36969.

I will update this patch tomorrow.

[arphaman]

• Split the header
• Remove DiagnosticOr in favour of Expected that will use a DiagnosticError that was proposed in the other patch.
• Address the other review comments

include/clang/Tooling/Refactoring/RefactoringOperationController.h

19

Bad comment. I think inputs is more descriptive.

include/clang/Tooling/Refactoring/RefactoringResult.h

27

Nah, it's more convenient to be able to return a single AtomicChanges without an explicit initializer I think.

35

No, that was a workaround for a non-const member use. I'll use a const cast instead.

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

35

This class is not related to RequirementBase though. Were you talking about another class?

[ioeric]

Thanks for the changes! The code is much clearer.

I am wondering if the current design could be extended to support tools (or rules) that use AST matchers? Or is the selection expected to be powerful enough to replace AST matchers?

We have a few tools in clang-tools-extra (e.g. clang-move and change-namespace) and many internal tools that are based on AST matchers, but we would really like to move them into clang-refactor in the future :)

include/clang/Tooling/Refactoring/RefactoringActionRuleRequirements.h

26 ↗

(On Diff #112195)

Could you help me understand this class?

This seems to be a selection-specific requirement and should live in selection. It is also used in BaseSpecializedRule which seems to be a higher level of abstraction.

include/clang/Tooling/Refactoring/RefactoringResult.h

22

I'm a bit unsure about the abstraction of the refactoring result. I would expected refactoring results to be source changes always. Do you have any refactoring tool that outputs occurrences in mind?

27

+1 to explicit which could prevent unintentional conversion. RefactoringResult(Change); isn't too bad IMO.

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

56

Does detail mean internal implementation? Maybe use internal which is more commonly used for this?

[arphaman]

include/clang/Tooling/Refactoring/RefactoringResult.h

22

In Xcode we require rename to return symbol occurrences because the IDE is responsible for figuring out:

1. The new name. Thus we can't produce replacements when renaming because we don't know what the new name is when gathering the occurrences.
2. Whether these occurrences should be actually applied. Thus we can't produce replacements because it's up to the user to decide if they want to rename some occurrence in a comment for example.

In general 2) can be applied to tools like clang-refactor that could allow users to select occurrences that don't guarantee a direct semantic match (comments, etc.) in an interactive manner.

I think clangd has a rather naive rename support, so these points may not apply, but we may want to extend clangd's support for rename in the future as well.

[arphaman]

In D36075#851278, @ioeric wrote:

Thanks for the changes! The code is much clearer.

I am wondering if the current design could be extended to support tools (or rules) that use AST matchers? Or is the selection expected to be powerful enough to replace AST matchers?

We have a few tools in clang-tools-extra (e.g. clang-move and change-namespace) and many internal tools that are based on AST matchers, but we would really like to move them into clang-refactor in the future :)

The selection requirement is supposed to be orthogonal to AST matchers, not a replacement. It should be used when working with source selection in editors.

I did mess around with moving over clang-reorder-fields using this kind of model and didn't see any issues when using AST matchers. Essentially I used the requiredOption requirements and mapped them to run my matching code instead of using the selection requirement. Thus this requirement was satisfied only when the AST matchers were successful. It might be possible to simplify that pattern even further to make it simpler.

In D36075#851278, @ioeric wrote:

Thanks for the changes! The code is much clearer.

I am wondering if the current design could be extended to support tools (or rules) that use AST matchers? Or is the selection expected to be powerful enough to replace AST matchers?

We have a few tools in clang-tools-extra (e.g. clang-move and change-namespace) and many internal tools that are based on AST matchers, but we would really like to move them into clang-refactor in the future :)

[arphaman]

include/clang/Tooling/Refactoring/RefactoringActionRuleRequirements.h

26 ↗

(On Diff #112195)

It's just a container class that stores all information about the requiredSelection requirement. I agree about BaseSpecializedRule, that connection should be chopped. I will move the evaluation code into the requirement itself when I update the patch.

I would tend to disagree about moving it though, as SourceSelectionRequirement is a requirement first and I think that's why it should live with other requirements. Yes, it's related to selections, but it uses them to implement the requirement. I think it's better to keep requirements together, as opposed to having option requirements close to options, selection requirements close to selection, and so on. WDYT?

[arphaman]

• Rename detail to internal.
• Remove the BaseSpecializedRule.
• Simplify selection requirement and constraint evaluation.

[ioeric]

include/clang/Tooling/Refactoring/RefactoringActionRuleRequirements.h

26 ↗

(On Diff #112195)

Thanks!

Makes sense. We might want to put individual requirements into their own headers so that this doesn't grow into a huge file when more requirements are supported.

include/clang/Tooling/Refactoring/RefactoringActionRuleRequirementsInternal.h

42 ↗

(On Diff #112566)

It might worth having a comment explaining why and how Expected<Optional> is wrapped and unwrapped during the evaluation.

include/clang/Tooling/Refactoring/RefactoringActionRules.h

34

We might want to document supported requirements somewhere else so that we don't need to update this file every time a new requirement is added.

include/clang/Tooling/Refactoring/RefactoringOperation.h

1 ↗

(On Diff #112566)

s/RefactoringOperationController.h/RefactoringOperation.h/ :)

29 ↗

(On Diff #112566)

I found the name a bit confusing - RefactoringOperation sounds a bit like RefactoringAction.

Would it make sense to call this RefactoringContext or RefactoringRuleContext, if this stores states of a refactoring rule?

include/clang/Tooling/Refactoring/RefactoringResult.h

22

I feel occurrences are more of an intermediate state of a refactoring action than a result. I'm wondering if it makes sense to introduce a separate class to represent such intermediate states? I am a bit nervous to fuse multiple classes into one; the interfaces can get pretty ugly when more result kinds are added.

lib/Tooling/Refactoring/SourceSelectionConstraints.cpp

13 ↗

(On Diff #112566)

We are tempted to avoid using namespace if possible.

[arphaman]

include/clang/Tooling/Refactoring/RefactoringResult.h

22

Good point. I agree.

I think it would be better to differentiate between RefactoringActionRules then. Ordinary rules return a set of AtomicChanges instead of RefactoringResult. But then we could also have "interactive" rules that return "partial" results like symbol occurrences.

I think I'll try the following approach:

class RefactoringActionRule {
  virtual ~RefactoringActionRule() {}
};

class RefactoringActionSourceChangeRule: public RefactoringActionRule {
public:
  virtual Expected<Optional<AtomicChanges>>
  createSourceReplacements(RefactoringOperation &Operation) = 0;
};

class RefactoringActionSymbolOccurrencesRule: public RefactoringActionRule {
public:
  virtual Expected<Optional<SymbolOccurrences>>
  findSymbolOccurrences(RefactoringOperation &Operation) = 0;
};

[arphaman]

lib/Tooling/Refactoring/SourceSelectionConstraints.cpp

13 ↗

(On Diff #112566)

Why? It's not in a header. using namespace clang is the common practice across all of Clang's sources.

[alexander-shaposhnikov]

@arphaman

The selection requirement is supposed to be orthogonal to AST matchers, not a replacement. It should be used when working with source selection in editors. 
I did mess around with moving over clang-reorder-fields using this kind of model and didn't see any issues when using AST matchers. Essentially I used the  requiredOption requirements and mapped them to run my 
matching code instead of using the selection requirement. Thus this requirement was satisfied only when the AST matchers were successful. 
It might be possible to simplify that pattern even further to make it simpler.

that's great, i'm interested in this too and would be happy to see clang-reorder-fields moving to clang-refactor (pls, let me know if i can help make this happen)

[arphaman]

include/clang/Tooling/Refactoring/RefactoringActionRules.h

34

Do you think it should be in Clang's documentation? I can start on a new document there but I'd prefer to do it in a separate patch. WDYT?

[arphaman]

• Get rid of RefactoringResult in favour of different rule types.
• Rename RefactoringOperation to RefactoringRuleContext.
• Address a couple more comments.

[ioeric]

Thanks for the changes! Lgtm with a few nits.

include/clang/Tooling/Refactoring/RefactoringActionRules.h

34

Sure, this is fine for now. It would be nice to have proper documentation in the future when pieces get into places.

include/clang/Tooling/Refactoring/RefactoringActionRulesInternal.h

33 ↗

(On Diff #112678)

Why isn't this a interface in SpecificRefactoringRuleAdapter with return type Expected<Optional<T>>?

unittests/Tooling/RefactoringActionRulesTest.cpp

68

It would be nice to also rename the variable from Operation to Context.

[arphaman]

Thanks,

I'll start working on the documentation patch and will split follow-up clang-refactor patch into one or two parts today.

include/clang/Tooling/Refactoring/RefactoringActionRulesInternal.h

33 ↗

(On Diff #112678)

A method declaration in SpecificRefactoringRuleAdapter won't work since it won't be available in either the template specialisation or the deriving class as the classes won't be directly related. I could use a separate parent class independent of SpecificRefactoringRuleAdapter that declares a generic interface though.

[klimek]

cfe/trunk/include/clang/Tooling/Refactoring/RefactoringActionRule.h

23–37 ↗

(On Diff #112879)

Sorry for being late, was out on vacation.
Generally, why do we need this tag-based abstraction here instead of using the more typical OO double-dispatch where necessary?
(We do this in the AST a lot, but the AST is special, because there we want to implement a lot of different algorithms that rely on the node type, while I don't see how that applies here)

[arphaman]

cfe/trunk/include/clang/Tooling/Refactoring/RefactoringActionRule.h

23–37 ↗

(On Diff #112879)

Generally the clients will have to somehow distinguish between the types of results that are produced by rules to figure out what to do (e.g. AtomicChanges -> apply, SymbolOccurrences -> ask user, Continuation -> look for more ASTs). So far I've thought that the LLVM based dynamic casts will work well for this, e.g.

if (auto *Action = dyn_cast<SourceChangeRefactoringRule>()) {
  Expected<Optional<AtomicChanges>> Changes = Action->createSourceReplacements();
  applyChanges(Changes);
} else if (...) {
  ...
} else (...) {
   ...
}

But you're probably right, there might be a better way to do this rather than the tag based approach. Something like a consumer class that clients can implement that provides consumer functions that take in the specific results. I reckon a single consumer will actually work better in the long-run when we might Continuations that both return changes in the first TU and information for searches in other TUs. I'll see if I can get a patch out that removes this tag and uses the consumer approach.

[klimek]

cfe/trunk/include/clang/Tooling/Refactoring/RefactoringActionRule.h

23–37 ↗

(On Diff #112879)

Cool, looking forward to it :)

include/clang/Basic/AllDiagnostics.h

 #include "clang/AST/CommentDiagnostic.h"
 #include "clang/Analysis/AnalysisDiagnostic.h"
 #include "clang/Driver/DriverDiagnostic.h"
 #include "clang/Frontend/FrontendDiagnostic.h"
 #include "clang/Lex/LexDiagnostic.h"
 #include "clang/Parse/ParseDiagnostic.h"
 #include "clang/Sema/SemaDiagnostic.h"
 #include "clang/Serialization/SerializationDiagnostic.h"
+#include "clang/Tooling/Refactoring/RefactoringDiagnostic.h"
 
 namespace clang {
 template <size_t SizeOfStr, typename FieldType>
 class StringSizerHelper {
   static_assert(SizeOfStr <= FieldType(~0U), "Field too small!");
 public:
   enum { Size = SizeOfStr };
 };
 } // end namespace clang 
 
 #define STR_SIZE(str, fieldTy) clang::StringSizerHelper<sizeof(str)-1, \
                                                         fieldTy>::Size 
 
 #endif

include/clang/Basic/CMakeLists.txt

 macro(clang_diag_gen component)
   clang_tablegen(Diagnostic${component}Kinds.inc
     -gen-clang-diags-defs -clang-component=${component}
     SOURCE Diagnostic.td
     TARGET ClangDiagnostic${component})
 endmacro(clang_diag_gen)
 
 clang_diag_gen(Analysis)
 clang_diag_gen(AST)
 clang_diag_gen(Comment)
 clang_diag_gen(Common)
 clang_diag_gen(Driver)
 clang_diag_gen(Frontend)
 clang_diag_gen(Lex)
 clang_diag_gen(Parse)
+clang_diag_gen(Refactoring)
 clang_diag_gen(Sema)
 clang_diag_gen(Serialization)
 clang_tablegen(DiagnosticGroups.inc -gen-clang-diag-groups
   SOURCE Diagnostic.td
   TARGET ClangDiagnosticGroups)
 
 clang_tablegen(DiagnosticIndexName.inc -gen-clang-diags-index-name
   SOURCE Diagnostic.td

include/clang/Basic/Diagnostic.td

 include "DiagnosticASTKinds.td"
 include "DiagnosticAnalysisKinds.td"
 include "DiagnosticCommentKinds.td"
 include "DiagnosticCommonKinds.td"
 include "DiagnosticDriverKinds.td"
 include "DiagnosticFrontendKinds.td"
 include "DiagnosticLexKinds.td"
 include "DiagnosticParseKinds.td"
+include "DiagnosticRefactoringKinds.td"
 include "DiagnosticSemaKinds.td"
 include "DiagnosticSerializationKinds.td"
 

include/clang/Basic/DiagnosticIDs.h

enum {
       DIAG_START_FRONTEND      = DIAG_START_DRIVER          +  200,
       DIAG_START_SERIALIZATION = DIAG_START_FRONTEND        +  100,
       DIAG_START_LEX           = DIAG_START_SERIALIZATION   +  120,
       DIAG_START_PARSE         = DIAG_START_LEX             +  400,
       DIAG_START_AST           = DIAG_START_PARSE           +  500,
       DIAG_START_COMMENT       = DIAG_START_AST             +  110,
       DIAG_START_SEMA          = DIAG_START_COMMENT         +  100,
       DIAG_START_ANALYSIS      = DIAG_START_SEMA            + 3500,
-      DIAG_UPPER_LIMIT         = DIAG_START_ANALYSIS        +  100
+      DIAG_START_REFACTORING   = DIAG_START_ANALYSIS        +  100,
+      DIAG_UPPER_LIMIT         = DIAG_START_REFACTORING     +  500
     };
 
     class CustomDiagInfo;
 
     /// \brief All of the diagnostics that can be emitted by the frontend.
     typedef unsigned kind;
 
     // Get typedefs for common diagnostics.

include/clang/Basic/DiagnosticOr.h

+//===--- DiagnosticOr.h - Diagnostic "closures" -----------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Implements a partial diagnostic that can be emitted anwyhere
+/// in a DiagnosticBuilder stream.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_BASIC_DIAGNOSTIC_OR_H
+#define LLVM_CLANG_BASIC_DIAGNOSTIC_OR_H
+
+#include "clang/Basic/PartialDiagnostic.h"
+#include "llvm/Support/AlignOf.h"
+#include "llvm/Support/Compiler.h"
+
+namespace clang {
+
+/// Tagged union holding either a T or a PartialDiagnosticAt.
+///
+/// This class parallels llvm::Expected, but replaces Error with
+/// PartialDiagnosticAt.
+template <class T> class LLVM_NODISCARD DiagnosticOr {
+private:
+  using storage_type = T;
+  using reference = T &;
+  using const_reference = const T &;
+  using pointer = T *;
+  using const_pointer = const T *;
+
+public:
+  /// Create an DiagnosticOr<T> diagnostic value from the given partial
+  /// diagnostic.
+  DiagnosticOr(PartialDiagnosticAt Diagnostic) : HasDiagnostic(true) {
+    new (getDiagnosticStorage()) PartialDiagnosticAt(std::move(Diagnostic));
+  }
+
+  /// Create an DiagnosticOr<T> success value from the given OtherT value, which
+  /// must be convertible to T.
+  template <typename OtherT>
+  DiagnosticOr(
+      OtherT &&Val,
+      typename std::enable_if<std::is_convertible<OtherT, T>::value>::type * =
+          nullptr)
+      : HasDiagnostic(false) {
+    new (getStorage()) storage_type(std::forward<OtherT>(Val));
+  }
+
+  DiagnosticOr(DiagnosticOr<T> &&Other) { moveConstruct(std::move(Other)); }
+
+  DiagnosticOr<T> &operator=(DiagnosticOr<T> &&Other) {
+    moveAssign(std::move(Other));
+    return *this;
+  }
+
+  ~DiagnosticOr() {
+    if (!HasDiagnostic)
+      getStorage()->~storage_type();
+    else
+      getDiagnosticStorage()->~PartialDiagnosticAt();
+  }
+
+  /// Returns false if there is a diagnostic.
+  explicit operator bool() { return !HasDiagnostic; }
+
+  PartialDiagnosticAt &getDiagnostic() { return *getDiagnosticStorage(); }
+
+  const PartialDiagnosticAt &getDiagnostic() const {
+    return *getDiagnosticStorage();
+  }
+
+  pointer operator->() { return getStorage(); }
+
+  const_pointer operator->() const { return getStorage(); }
+
+  reference operator*() { return *getStorage(); }
+
+  const_reference operator*() const { return *getStorage(); }
+
+private:
+  void moveConstruct(DiagnosticOr<T> &&Other) {
+    HasDiagnostic = Other.HasDiagnostic;
+
+    if (!HasDiagnostic)
+      new (getStorage()) storage_type(std::move(*Other.getStorage()));
+    else
+      new (getDiagnosticStorage())
+          PartialDiagnosticAt(std::move(*Other.getDiagnosticStorage()));
+  }
+
+  void moveAssign(DiagnosticOr<T> &&Other) {
+    this->~DiagnosticOr();
+    new (this) DiagnosticOr<T>(std::move(Other));
+  }
+
+  storage_type *getStorage() {
+    assert(!HasDiagnostic && "Cannot get value when a diagnostic exists!");
+    return reinterpret_cast<storage_type *>(TStorage.buffer);
+  }
+
+  const storage_type *getStorage() const {
+    assert(!HasDiagnostic && "Cannot get value when a diagnostic exists!");
+    return reinterpret_cast<const storage_type *>(TStorage.buffer);
+  }
+
+  PartialDiagnosticAt *getDiagnosticStorage() {
+    assert(HasDiagnostic && "Cannot get diagnostic when a value exists!");
+    return reinterpret_cast<PartialDiagnosticAt *>(DiagnosticStorage.buffer);
+  }
+
+  const PartialDiagnosticAt *getDiagnosticStorage() const {
+    assert(HasDiagnostic && "Cannot get diagnostic when a value exists!");
+    return reinterpret_cast<const PartialDiagnosticAt *>(
+        DiagnosticStorage.buffer);
+  }
+
+  union {
+    llvm::AlignedCharArrayUnion<storage_type> TStorage;
+    llvm::AlignedCharArrayUnion<PartialDiagnosticAt> DiagnosticStorage;
+  };
+  bool HasDiagnostic : 1;
+};
+
+} // end namespace clang
+
+#endif // LLVM_CLANG_BASIC_DIAGNOSTIC_OR_H

include/clang/Basic/DiagnosticRefactoringKinds.td

+//==--- DiagnosticRefactoringKinds.td - refactoring diagnostics -----------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+//===----------------------------------------------------------------------===//
+// Refactoring Diagnostics
+//===----------------------------------------------------------------------===//
+
+let Component = "Refactoring" in {
+
+let CategoryName = "Refactoring Invocation Issue" in {
+
+def err_refactor_rule_function_failed : Error<"%0">;
+
+}
+
+} // end of Refactoring diagnostics

include/clang/Basic/LLVM.h

namespace llvm {
   class Twine;
   template<typename T> class ArrayRef;
   template<typename T> class MutableArrayRef;
   template<typename T> class OwningArrayRef;
   template<unsigned InternalLen> class SmallString;
   template<typename T, unsigned N> class SmallVector;
   template<typename T> class SmallVectorImpl;
   template<typename T> class Optional;
+  template <class T> class Expected;
 
   template<typename T>
   struct SaveAndRestore;
 
   // Reference counting.
   template <typename T> class IntrusiveRefCntPtr;
   template <typename T> struct IntrusiveRefCntPtrInfo;
   template <class Derived> class RefCountedBase;
namespace clang {
   using llvm::ArrayRef;
   using llvm::MutableArrayRef;
   using llvm::OwningArrayRef;
   using llvm::SmallString;
   using llvm::SmallVector;
   using llvm::SmallVectorImpl;
   using llvm::SaveAndRestore;
 
+  // Error handling.
+  using llvm::Expected;
+
   // Reference counting.
   using llvm::IntrusiveRefCntPtr;
   using llvm::IntrusiveRefCntPtrInfo;
   using llvm::RefCountedBase;
 
   using llvm::raw_ostream;
   using llvm::raw_pwrite_stream;
 } // end namespace clang.
 
 #endif

include/clang/Tooling/Refactoring/AtomicChange.h

public:
   /// \p KeyPosition should be the location of the key syntactical element that
   /// is being changed, e.g. the call to a refactored method.
   AtomicChange(const SourceManager &SM, SourceLocation KeyPosition);
 
   /// \brief Creates an atomic change for \p FilePath with a customized key.
   AtomicChange(llvm::StringRef FilePath, llvm::StringRef Key)
       : Key(Key), FilePath(FilePath) {}
 
+  AtomicChange(AtomicChange &&) = default;
+  AtomicChange(const AtomicChange &) = default;
+
+  AtomicChange &operator=(AtomicChange &&) = default;
+  AtomicChange &operator=(const AtomicChange &) = default;
+
   /// \brief Returns the atomic change as a YAML string.
   std::string toYAMLString();
 
   /// \brief Converts a YAML-encoded automic change to AtomicChange.
   static AtomicChange convertFromYAML(llvm::StringRef YAMLContent);
 
   /// \brief Returns the key of this change, which is a concatenation of the
   /// file name and offset of the key position.

include/clang/Tooling/Refactoring/RefactoringActionRules.h

+//===--- RefactoringActionRules.h - Clang refactoring library -------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H
+#define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H
+
+#include "clang/Basic/DiagnosticOr.h"
+#include "clang/Basic/LLVM.h"
+#include "clang/Tooling/Refactoring/RefactoringDiagnostic.h"
+#include "clang/Tooling/Refactoring/RefactoringOperationController.h"
+#include "clang/Tooling/Refactoring/RefactoringResult.h"
+#include "clang/Tooling/Refactoring/SourceSelectionConstraints.h"
+#include "llvm/Support/Error.h"
+#include <type_traits>
+
+namespace clang {
+namespace tooling {
+
+/// A common refactoring action rule interface.
+class RefactoringActionRule {
+public:
+  virtual ~RefactoringActionRule() {}
+
+  /// The refactoring engine calls this method when trying to perform a
+  /// refactoring operation.
+  ///
+  /// The specific rule must return a diagnostic when the refactoring action
+  /// couldn't be initiated/performed, or a valid refactoring result when the
+  /// rule's function runs successfully.
+  virtual DiagnosticOr<RefactoringResult>
+  perform(RefactoringOperationController &Controller) = 0;
+};
+
+/// A set of refactoring action rules that should have unique initiation
+/// requirements.
+using RefactoringActionRules =
+    std::vector<std::unique_ptr<RefactoringActionRule>>;
+
+namespace refactoring_action_rules {
+
+namespace detail {
+
+struct RequirementBase {};
+
+} // end namespace detail
+
+namespace traits {
+
+/// A type trait that returns true iff the given type is a valid rule
+/// requirement.
+template <typename First, typename... Rest>
+struct IsRequirement : std::conditional<IsRequirement<First>::value &&
+                                            IsRequirement<Rest...>::value,
+                                        std::true_type, std::false_type>::type {
+};
+
+template <typename T>
+struct IsRequirement<T>
+    : std::conditional<std::is_base_of<detail::RequirementBase, T>::value,
+                       std::true_type, std::false_type>::type {};
+
+} // end namespace traits
+
+namespace detail {
+
+/// Defines a type alias of type \T when given \c DiagnosticOr<T>, or
+/// \c T otherwise.
+template <typename T> struct DropDiagnosticOr { using Type = T; };
+
+template <typename T> struct DropDiagnosticOr<DiagnosticOr<T>> {
+  using Type = T;
+};
+
+/// The \c requiredSelection refactoring action requirement is represented
+/// using this type.
+template <typename InputT, typename OutputT, typename RequirementT>
+struct SourceSelectionRequirement
+    : std::enable_if<selection::traits::IsConstraint<InputT>::value &&
+                         selection::traits::IsRequirement<RequirementT>::value,
+                     RequirementBase>::type {
+  using OutputType = typename DropDiagnosticOr<OutputT>::Type;
+
+  SourceSelectionRequirement(const RequirementT &Requirement)
+      : Requirement(Requirement) {}
+
+private:
+  const RequirementT Requirement;
+  friend class BaseSpecializedRule;
+};
+
+/// A wrapper class around \c RefactoringActionRule that defines some helper
+/// methods that are used by the subclasses.
+class BaseSpecializedRule : public RefactoringActionRule {
+protected:
+  /// Evaluates a source selection action rule requirement.
+  template <typename InputT, typename OutputT, typename RequirementT>
+  static DiagnosticOr<typename DropDiagnosticOr<OutputT>::Type>
+  evaluate(RefactoringOperationController &Controller,
+           const SourceSelectionRequirement<InputT, OutputT, RequirementT>
+               &SelectionRequirement) {
+    Optional<InputT> Value = evalSelection<InputT>(Controller);
+    if (!Value)
+      return invalidSelectionError();
+    return std::move(
+        SelectionRequirement.Requirement.evaluateSelection(*Value));
+  }
+
+  /// Returns \c T when given \c DiagnosticOr<T>, or \c T otherwise.
+  template <typename T> static T &&removeDiagOr(DiagnosticOr<T> &&X) {
+    assert(X && "unexpected diagnostic!");
+    return std::move(*X);
+  }
+  template <typename T> static T &&removeDiagOr(T &&X) { return std::move(X); }
+
+  using OptionalDiag = Optional<PartialDiagnosticAt>;
+
+  /// Scans the tuple and returns a \c PartialDiagnosticAt
+  /// from the first invalid \c DiagnosticOr value. Returns \c None if all
+  /// values are valid.
+  template <typename FirstT, typename... RestT>
+  static OptionalDiag findDiag(FirstT &First, RestT &... Rest) {
+    OptionalDiag Result = takeDiagOrNone(First);
+    if (Result)
+      return Result;
+    return findDiag(Rest...);
+  }
+
+private:
+  /// Evaluates a selection constraint.
+  template <typename T>
+  static typename std::enable_if<selection::traits::IsConstraint<T>::value,
+                                 llvm::Optional<T>>::type
+  evalSelection(RefactoringOperationController &Controller);
+
+  static OptionalDiag findDiag() { return OptionalDiag(); }
+  template <typename T> static OptionalDiag takeDiagOrNone(T &) {
+    return OptionalDiag();
+  }
+  template <typename T>
+  static OptionalDiag takeDiagOrNone(DiagnosticOr<T> &Diag) {
+    if (!Diag)
+      return std::move(Diag.getDiagnostic());
+    return OptionalDiag();
+  }
+};
+
+/// Evaluates the \c selection::SourceSelectionRange constraint.
+template <>
+llvm::Optional<selection::SourceSelectionRange> inline BaseSpecializedRule::
+    evalSelection<selection::SourceSelectionRange>(
+        RefactoringOperationController &Controller) {
+  SourceRange R = Controller.getSelectionRange();
+  if (R.isInvalid())
+    return None;
+  return selection::SourceSelectionRange(Controller.getSources(), R);
+}
+
+/// A specialized refactoring action rule that calls the stored function once
+/// all the of the requirements are fullfilled. The values produced during the
+/// evaluation of requirements are passed to the stored function.
+template <typename FunctionType, typename... RequirementTypes>
+class PlainFunctionRule final : public BaseSpecializedRule {
+public:
+  PlainFunctionRule(FunctionType Function,
+                    std::tuple<RequirementTypes...> &&Requirements)
+      : Function(Function), Requirements(std::move(Requirements)) {}
+
+  DiagnosticOr<RefactoringResult>
+  perform(RefactoringOperationController &Controller) override {
+    return performImpl(Controller,
+                       llvm::index_sequence_for<RequirementTypes...>());
+  }
+
+private:
+  template <size_t... Is>
+  DiagnosticOr<RefactoringResult>
+  performImpl(RefactoringOperationController &Controller,
+              llvm::index_sequence<Is...>) {
+    // Initiate the operation.
+    auto Values =
+        std::make_tuple(evaluate(Controller, std::get<Is>(Requirements))...);
+    OptionalDiag InitiationFailure = findDiag(std::get<Is>(Values)...);
+    if (InitiationFailure)
+      return std::move(*InitiationFailure);
+    // Perform the operation.
+    Expected<RefactoringResult> Result =
+        Function(removeDiagOr(std::move(std::get<Is>(Values)))...);
+    if (Result)
+      return std::move(*Result);
+    std::string Error = llvm::toString(Result.takeError());
+    return PartialDiagnosticAt(
+        SourceLocation(),
+        PartialDiagnostic(diag::err_refactor_rule_function_failed,
+                          Controller.getDiagnosticStorage())
+            << Error);
+  }
+
+  FunctionType Function;
+  std::tuple<RequirementTypes...> Requirements;
+};
+
+} // end namespace detail
+
+/// Creates a new refactoring action rule that invokes the given function once
+/// all of the requirements are satisfied. The values produced during the
+/// evaluation of requirements are passed to the given function (in the order of
+/// requirements).
+///
+/// \param RefactoringFunction the function that will perform the refactoring
+/// once the requirements are satisfied.
+///
+/// \param Requirements a set of rule requirements that have to be satisfied.
+/// Each requirement must be a valid requirement, i.e. the value of
+/// \c traits::IsRequirement<T> must be true. The following requirements are
+/// currently supported:
+///
+///  - requiredSelection: The refactoring function won't be invoked unless the
+///                       given selection requirement is satisfied.
+template <typename... RequirementTypes>
+std::unique_ptr<RefactoringActionRule>
+apply(Expected<RefactoringResult> (*RefactoringFunction)(
+          typename RequirementTypes::OutputType...),
+      const RequirementTypes &... Requirements) {
+  static_assert(traits::IsRequirement<RequirementTypes...>::value,
+                "invalid refactoring action rule requirement");
+  return llvm::make_unique<detail::PlainFunctionRule<
+      decltype(RefactoringFunction), RequirementTypes...>>(
+      RefactoringFunction, std::make_tuple(Requirements...));
+}
+
+/// Creates a selection requirement from the given requirement.
+///
+/// Requirements must subclass \c selection::Requirement and implement
+/// evaluateSelection member function.
+template <typename T>
+detail::SourceSelectionRequirement<
+    typename selection::detail::EvaluateSelectionChecker<
+        decltype(&T::evaluateSelection)>::ArgType,
+    typename selection::detail::EvaluateSelectionChecker<
+        decltype(&T::evaluateSelection)>::ReturnType,
+    T>
+requiredSelection(
+    const T &Requirement,
+    typename std::enable_if<selection::traits::IsRequirement<T>::value>::type
+        * = nullptr) {
+  return detail::SourceSelectionRequirement<
+      typename selection::detail::EvaluateSelectionChecker<decltype(
+          &T::evaluateSelection)>::ArgType,
+      typename selection::detail::EvaluateSelectionChecker<decltype(
+          &T::evaluateSelection)>::ReturnType,
+      T>(Requirement);
+}
+
+template <typename T>
+void requiredSelection(
+    const T &,
+    typename std::enable_if<
+        !std::is_base_of<selection::Requirement, T>::value>::type * = nullptr) {
+  static_assert(
+      sizeof(T) && false,
+      "selection requirement must be a class derived from Requirement");
+}
+
+} // end namespace refactoring_action_rules
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H

include/clang/Tooling/Refactoring/RefactoringDiagnostic.h

+//===--- RefactoringDiagnostic.h - ------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTORING_REFACTORINGDIAGNOSTIC_H
+#define LLVM_CLANG_TOOLING_REFACTORING_REFACTORINGDIAGNOSTIC_H
+
+#include "clang/Basic/Diagnostic.h"
+#include "clang/Basic/PartialDiagnostic.h"
+
+namespace clang {
+namespace diag {
+enum {
+#define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
+             SHOWINSYSHEADER, CATEGORY)                                        \
+  ENUM,
+#define REFACTORINGSTART
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+#undef DIAG
+  NUM_BUILTIN_REFACTORING_DIAGNOSTICS
+};
+} // end namespace diag
+
+namespace tooling {
+
+/// Returns a refactoring diagnostic that represents a failure of initiation of
+/// a refactoring action which occurred because the source selection doesn't
+/// contain the required AST nodes.
+inline PartialDiagnosticAt invalidSelectionError() {
+  // Create an empty diagnostic that represents an invalid selection. The
+  // individual engines will interpret it differently - clang-refactor will
+  // convert it to a proper diagnostic, while IDEs can just ignore it.
+  return PartialDiagnosticAt(
+      SourceLocation(), PartialDiagnostic(PartialDiagnostic::NullDiagnostic()));
+}
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTORING_REFACTORINGDIAGNOSTIC_H

include/clang/Tooling/Refactoring/RefactoringOperationController.h

+//===--- RefactoringOperationController.h - Clang refactoring library -----===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_OPERATION_CONTROLLER_H
+#define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_OPERATION_CONTROLLER_H
+
+#include "clang/Basic/PartialDiagnostic.h"
+#include "clang/Basic/SourceManager.h"
+
+namespace clang {
+namespace tooling {
+
+/// Encapsulates all of the possible state that an individual refactoring
+/// operation might have. Controls the process of initiation of refactoring
+/// operations, by feeding the right information to the functions that
+/// evaluate the refactoring action rule requirements.
+class RefactoringOperationController {
+public:
+  RefactoringOperationController(const SourceManager &SM) : SM(SM) {}
+
+  PartialDiagnostic::StorageAllocator &getDiagnosticStorage() {
+    return DiagnosticStorage;
+  }
+
+  const SourceManager &getSources() const { return SM; }
+
+  /// Returns the current source selection range as set by the
+  /// refactoring engine. Can be invalid.
+  SourceRange getSelectionRange() const { return SelectionRange; }
+
+  void setSelectionRange(SourceRange R) { SelectionRange = R; }
+
+private:
+  const SourceManager &SM;
+  SourceRange SelectionRange;
+  PartialDiagnostic::StorageAllocator DiagnosticStorage;
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_OPERATION_CONTROLLER_H

include/clang/Tooling/Refactoring/RefactoringResult.h

+//===--- RefactoringResult.h - Clang refactoring library ------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_RESULT_H
+#define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_RESULT_H
+
+#include "clang/Tooling/Refactoring/AtomicChange.h"
+
+namespace clang {
+namespace tooling {
+
+/// Refactoring result is a variant that stores a set of source changes or
+/// a set of found symbol occurrences.
+struct RefactoringResult {
+  enum ResultKind {
+    /// A set of source replacements represented using a vector of
+    /// \c AtomicChanges.
+    AtomicChanges
+  };
+
+  RefactoringResult(AtomicChange Change) : Kind(AtomicChanges) {
+    Changes.push_back(std::move(Change));
+  }
+  RefactoringResult(RefactoringResult &&Other) = default;
+  RefactoringResult &operator=(RefactoringResult &&Other) = default;
+
+  ResultKind getKind() const { return Kind; }
+
+  llvm::MutableArrayRef<AtomicChange> getChanges() {
+    assert(getKind() == AtomicChanges &&
+           "Refactoring didn't produce atomic changes");
+    return Changes;
+  }
+
+private:
+  ResultKind Kind;
+  std::vector<AtomicChange> Changes;
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_RESULT_H

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

+//===--- SourceSelectionConstraints.h - Clang refactoring library ---------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_SOURCE_SELECTION_CONSTRAINTS_H
+#define LLVM_CLANG_TOOLING_REFACTOR_SOURCE_SELECTION_CONSTRAINTS_H
+
+#include "clang/Basic/SourceLocation.h"
+#include <type_traits>
+
+namespace clang {
+namespace tooling {
+namespace selection {
+
+/// This constraint is satisfied when any portion of the source text is
+/// selected. It can be used be used to obtain the raw source selection range.
+struct SourceSelectionRange {
+  SourceSelectionRange(const SourceManager &SM, SourceRange Range)
+      : SM(SM), Range(Range) {}
+
+  const SourceManager &getSources() const { return SM; }
+  SourceRange getRange() const { return Range; }
+
+private:
+  const SourceManager &SM;
+  SourceRange Range;
+};
+
+/// A custom selection requirement.
+class Requirement {
+  /// Subclasses must implement 'T evaluateSelection(SelectionConstraint) const'
+  /// member function. \c T is used to determine the return type that is
+  /// passed to the refactoring rule's function.
+  /// If T is \c DiagnosticOr<S> , then \c S is passed to the rule's function
+  /// using move semantics.
+  /// Otherwise, T is passed to the function directly using move semantics.
+  ///
+  /// The different return type rules allow refactoring actions to fail
+  /// initiation when the relevant portions of AST aren't selected.
+};
+
+namespace traits {
+
+/// A type trait that returns true iff the given type is a valid selection
+/// constraint.
+template <typename T> struct IsConstraint : public std::false_type {};
+
+} // end namespace traits
+
+namespace detail {
+
+template <typename T> struct EvaluateSelectionChecker : std::false_type {};
+
+template <typename T, typename R, typename A>
+struct EvaluateSelectionChecker<R (T::*)(A) const> : std::true_type {
+  using ReturnType = R;
+  using ArgType = A;
+};
+
+template <typename T> class Identity : public Requirement {
+public:
+  T evaluateSelection(T Value) const { return std::move(Value); }
+};
+
+} // end namespace detail
+
+/// A identity function that returns the given selection constraint is provided
+/// for convenience, as it can be passed to \c requiredSelection directly.
+template <typename T> detail::Identity<T> identity() {
+  static_assert(
+      traits::IsConstraint<T>::value,
+      "selection::identity can be used with selection constraints only");
+  return detail::Identity<T>();
+}
+
+namespace traits {
+
+template <>
+struct IsConstraint<SourceSelectionRange> : public std::true_type {};
+
+/// A type trait that returns true iff \c T is a valid selection requirement.
+template <typename T>
+struct IsRequirement
+    : std::conditional<
+          std::is_base_of<Requirement, T>::value &&
+              detail::EvaluateSelectionChecker<decltype(
+                  &T::evaluateSelection)>::value &&
+              IsConstraint<typename detail::EvaluateSelectionChecker<decltype(
+                  &T::evaluateSelection)>::ArgType>::value,
+          std::true_type, std::false_type>::type {};
+
+} // end namespace traits
+} // end namespace selection
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_SOURCE_SELECTION_CONSTRAINTS_H

lib/Basic/DiagnosticIDs.cpp

 
 struct StaticDiagInfoRec {
   uint16_t DiagID;
   unsigned DefaultSeverity : 3;
   unsigned Class : 3;
   unsigned SFINAE : 2;
   unsigned WarnNoWerror : 1;
   unsigned WarnShowInSystemHeader : 1;
-  unsigned Category : 5;
+  unsigned Category : 6;
 
   uint16_t OptionGroupIndex;
 
   uint16_t DescriptionLen;
   const char *DescriptionStr;
 
   unsigned getOptionGroupIndex() const {
     return OptionGroupIndex;

 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
 #undef DIAG
 };
 
 static const unsigned StaticDiagInfoSize = llvm::array_lengthof(StaticDiagInfo);
 
 /// GetDiagInfo - Return the StaticDiagInfoRec entry for the specified DiagID,
 /// or null if the ID is invalid.
 static const StaticDiagInfoRec *GetDiagInfo(unsigned DiagID) {

 CATEGORY(FRONTEND, DRIVER)
 CATEGORY(SERIALIZATION, FRONTEND)
 CATEGORY(LEX, SERIALIZATION)
 CATEGORY(PARSE, LEX)
 CATEGORY(AST, PARSE)
 CATEGORY(COMMENT, AST)
 CATEGORY(SEMA, COMMENT)
 CATEGORY(ANALYSIS, SEMA)
+CATEGORY(REFACTORING, ANALYSIS)
 #undef CATEGORY
 
   // Avoid out of bounds reads.
   if (ID + Offset >= StaticDiagInfoSize)
     return nullptr;
 
   assert(ID < StaticDiagInfoSize && Offset < StaticDiagInfoSize);
 

tools/diagtool/DiagnosticNames.cpp

 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
 #undef DIAG
 };
 
 static bool orderByID(const DiagnosticRecord &Left,
                       const DiagnosticRecord &Right) {
   return Left.DiagID < Right.DiagID;
 }
 

unittests/Tooling/CMakeLists.txt

add_clang_unittest(ToolingTests
   FixItTest.cpp
   LookupTest.cpp
   QualTypeNamesTest.cpp
   RecursiveASTVisitorTest.cpp
   RecursiveASTVisitorTestCallVisitor.cpp
   RecursiveASTVisitorTestDeclVisitor.cpp
   RecursiveASTVisitorTestExprVisitor.cpp
   RecursiveASTVisitorTestTypeLocVisitor.cpp
+  RefactoringActionRulesTest.cpp
   RefactoringCallbacksTest.cpp
   RefactoringTest.cpp
   ReplacementsYamlTest.cpp
   RewriterTest.cpp
   ToolingTest.cpp
   )
 
 target_link_libraries(ToolingTests

unittests/Tooling/RefactoringActionRulesTest.cpp

+//===- unittest/Tooling/RefactoringTestActionRulesTest.cpp ----------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "ReplacementTest.h"
+#include "RewriterTestContext.h"
+#include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Refactoring/RefactoringActionRules.h"
+#include "clang/Tooling/Tooling.h"
+#include "llvm/Support/Errc.h"
+#include "gtest/gtest.h"
+
+using namespace clang;
+using namespace tooling;
+using namespace refactoring_action_rules;
+
+namespace {
+
+class RefactoringActionRulesTest : public ::testing::Test {
+protected:
+  void SetUp() override {
+    Context.Sources.setMainFileID(
+        Context.createInMemoryFile("input.cpp", DefaultCode));
+  }
+
+  RewriterTestContext Context;
+  std::string DefaultCode = std::string(100, 'a');
+};
+
+TEST_F(RefactoringActionRulesTest, MyFirstRefactoringRule) {
+  auto ReplaceAWithB =
+      [](std::pair<selection::SourceSelectionRange, int> Selection)
+      -> Expected<RefactoringResult> {
+    const SourceManager &SM = Selection.first.getSources();
+    SourceLocation Loc = Selection.first.getRange().getBegin().getLocWithOffset(
+        Selection.second);
+    AtomicChange Change(SM, Loc);
+    llvm::Error E = Change.replace(SM, Loc, 1, "b");
+    if (E)
+      return std::move(E);
+    return Change;
+  };
+  class SelectionRequirement : public selection::Requirement {
+  public:
+    std::pair<selection::SourceSelectionRange, int>
+    evaluateSelection(selection::SourceSelectionRange Selection) const {
+      return std::make_pair(Selection, 20);
+    }
+  };
+  auto Rule = apply(ReplaceAWithB, requiredSelection(SelectionRequirement()));
+
+  // When the requirements are satisifed, the rule's function must be invoked.
+  {
+    RefactoringOperationController Operation(Context.Sources);
+    SourceLocation Cursor =
+        Context.Sources.getLocForStartOfFile(Context.Sources.getMainFileID())
+            .getLocWithOffset(10);
+    Operation.setSelectionRange({Cursor, Cursor});
+
+    DiagnosticOr<RefactoringResult> DiagOrResult = Rule->perform(Operation);
+    ASSERT_FALSE(!DiagOrResult);
+    RefactoringResult Result = std::move(*DiagOrResult);
+    ASSERT_EQ(Result.getKind(), RefactoringResult::AtomicChanges);
+    ASSERT_EQ(Result.getChanges().size(), 1u);
+    std::string YAMLString = Result.getChanges()[0].toYAMLString();
+
+    ASSERT_STREQ("---\n"
+                 "Key:             'input.cpp:30'\n"
+                 "FilePath:        input.cpp\n"
+                 "Error:           ''\n"
+                 "InsertedHeaders: \n"
+                 "RemovedHeaders:  \n"
+                 "Replacements:    \n" // Extra whitespace here!
+                 "  - FilePath:        input.cpp\n"
+                 "    Offset:          30\n"
+                 "    Length:          1\n"
+                 "    ReplacementText: b\n"
+                 "...\n",
+                 YAMLString.c_str());
+  }
+
+  // When one of the requirements is not satisfied, perform should return either
+  // None or a valid diagnostic.
+  {
+    RefactoringOperationController Operation(Context.Sources);
+    DiagnosticOr<RefactoringResult> DiagOrResult = Rule->perform(Operation);
+
+    // A failure to select returns the invalidSelectionError.
+    ASSERT_TRUE(!DiagOrResult);
+    EXPECT_EQ(DiagOrResult.getDiagnostic().first, SourceLocation());
+    EXPECT_EQ(DiagOrResult.getDiagnostic().second.getDiagID(), 0u);
+  }
+}
+
+TEST_F(RefactoringActionRulesTest, ReturnError) {
+  Expected<RefactoringResult> (*Func)(selection::SourceSelectionRange) =
+      [](selection::SourceSelectionRange) -> Expected<RefactoringResult> {
+    return llvm::make_error<llvm::StringError>(
+        "Error", std::make_error_code(std::errc::bad_message));
+  };
+  auto Rule =
+      apply(Func, requiredSelection(
+                      selection::identity<selection::SourceSelectionRange>()));
+
+  RefactoringOperationController Operation(Context.Sources);
+  SourceLocation Cursor =
+      Context.Sources.getLocForStartOfFile(Context.Sources.getMainFileID());
+  Operation.setSelectionRange({Cursor, Cursor});
+  DiagnosticOr<RefactoringResult> Result = Rule->perform(Operation);
+
+  ASSERT_TRUE(!Result);
+  SmallString<100> Str;
+  Result.getDiagnostic().second.EmitToString(Context.Diagnostics, Str);
+  EXPECT_EQ(Str.str(), "Error");
+}
+
+TEST_F(RefactoringActionRulesTest, ReturnInitiationDiagnostic) {
+  unsigned DiagID = Context.Diagnostics.getCustomDiagID(
+      DiagnosticsEngine::Error, "Diagnostic: %0");
+  RefactoringOperationController Operation(Context.Sources);
+  PartialDiagnostic Diag(DiagID, Operation.getDiagnosticStorage());
+
+  class SelectionRequirement : public selection::Requirement {
+  public:
+    const PartialDiagnostic &Diag;
+    SelectionRequirement(const PartialDiagnostic &Diag) : Diag(Diag) {}
+
+    DiagnosticOr<int>
+    evaluateSelection(selection::SourceSelectionRange Selection) const {
+      return PartialDiagnosticAt(Selection.getRange().getBegin(),
+                                 Diag << "test");
+    }
+  };
+  auto Rule = apply(
+      [](int) -> Expected<RefactoringResult> {
+        llvm::report_fatal_error("Should not run!");
+      },
+      requiredSelection(SelectionRequirement(Diag)));
+
+  SourceLocation Cursor =
+      Context.Sources.getLocForStartOfFile(Context.Sources.getMainFileID());
+  Operation.setSelectionRange({Cursor, Cursor});
+  DiagnosticOr<RefactoringResult> Result = Rule->perform(Operation);
+
+  ASSERT_TRUE(!Result);
+  EXPECT_EQ(Result.getDiagnostic().first, Cursor);
+  SmallString<100> Str;
+  Result.getDiagnostic().second.EmitToString(Context.Diagnostics, Str);
+  EXPECT_EQ(Str.str(), "Diagnostic: test");
+}
+
+} // end anonymous namespace