[refactor] add clang-refactor tool with initial testing support and local-rename action

[arphaman]

Summary

This patch depends on https://reviews.llvm.org/D36075 and https://reviews.llvm.org/D36156.

It introduces the clang-refactor tool alongside the local-rename action which is uses the existing renaming engine used by clang-rename. The tool doesn't actually perform the source transformations yet, it just provides testing support. I've moved one test from clang-rename over right now, but will move the others if the general direction of this patch is accepted.

The following options are supported by clang-refactor:

• -v: use verbose output
• -dump: dump results instead of applying them
• -no-dbs: avoid searching/loading databases like compilation database and/or indexer stores/databases
• -selection: The source range that corresponds to the portion of the source that's selected (currently only special command test:<file> is supported).

The testing support provided by clang-refactor is described below:
When -selection=test:<file> is given, clang-refactor will parse the selection commands from that file. The selection commands are grouped and the specified refactoring action invoked by the tool. Each command in a group is expected to produce an identical result. The precise syntax for the selection commands is described in a comment for findTestSelectionRangesIn in TestSupport.h.

Thanks for taking a look!

[arphaman]

Rebase on top of trunk and https://reviews.llvm.org/D37210.

Ping.

[klimek]

One of my main concerns is still that I don't see the need for all the template magic yet :) Why doesn't everybody use the RefactoringResult we define here?

test/Refactor/LocalRename/Field.cpp

4

Does this just test the selection?

tools/clang-refactor/ClangRefactor.cpp

135

Can we use composition instead of inheritance here?

[arphaman]

In D36574#858763, @klimek wrote:

One of my main concerns is still that I don't see the need for all the template magic yet :) Why doesn't everybody use the RefactoringResult we define here?

This refactoring result is only really useful for the test part of clang-refactor so you can compare two results.

The non-test part of clang-refactor and other clients don't really need an abstract interface for results as they will have different code for different results anyway.

[arphaman]

test/Refactor/LocalRename/Field.cpp

4

No, this is the moved clang-rename/Field.cpp test that tests local-rename. I will move the other tests when this patch is accepted.

[arphaman]

Get rid of inheritance of RefactoringEngine by getting rid of the class itself.

[arphaman]

In D36574#858763, @klimek wrote:

One of my main concerns is still that I don't see the need for all the template magic yet :) Why doesn't everybody use the RefactoringResult we define here?

@klimek, are you talking about the template usage in this patch or the whole approach in general? I can probably think of some way to reduce the template boilerplate if you are talking about the general approach.

[klimek]

In D36574#860197, @arphaman wrote:

In D36574#858763, @klimek wrote:

One of my main concerns is still that I don't see the need for all the template magic yet :) Why doesn't everybody use the RefactoringResult we define here?

@klimek, are you talking about the template usage in this patch or the whole approach in general? I can probably think of some way to reduce the template boilerplate if you are talking about the general approach.

Talking about the approach in general :)

test/Refactor/LocalRename/Field.cpp

4

Ok, then I find this test really hard to read - where does it check what the symbol was replaced with?

[ioeric]

include/clang/Tooling/Refactoring/RefactoringAction.h

21

Please add documentation for the class.

I appreciate your RFC that explains all these concepts; it would be nice if you could move some key concepts into the code documentation since we couldn't expect future readers to refer to the RFC. Thanks! ;)

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

42

when?

45–47

Can we pass RefactoringRuleContext instead of ASTRefactoringContext and get rules can get AST context from the rule context? I'm a bit nervous about having different contexts.

Maybe we should have just one interface T evaluateSelection(RefactoringRuleContext, SelectionConstraint) const. I think the rule context can be useful for all rules.

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

35–82

nit: It's a common practice to wrap implementations in namespaces instead of using using namespace. It becomes hard to manage scopes/namespaces when there are using namespaces.

tools/clang-refactor/ClangRefactor.cpp

61

I think you would get a conflict of positional args when you have multiple sub-command instances.

Any reason not to use clang::tooling::CommonOptionsParser which takes care of sources and compilation options for you?

73

Same here. There could be potential conflict among subcommands.

Also please provide more detailed description of this option; it is not obvious to users what a selection is.

313

Do we need a FIXME here? It seems that this simply finds the first command that is available? What if there are more than one commands that satisfy the requirements?

[arphaman]

In D36574#860203, @klimek wrote:

In D36574#860197, @arphaman wrote:

In D36574#858763, @klimek wrote:

One of my main concerns is still that I don't see the need for all the template magic yet :) Why doesn't everybody use the RefactoringResult we define here?

@klimek, are you talking about the template usage in this patch or the whole approach in general? I can probably think of some way to reduce the template boilerplate if you are talking about the general approach.

Talking about the approach in general :)

I'll work on a patch for a simpler solution as well then. It'll probably be dependent on this one though. I'm pretty sure I need some template magic to figure out how to connect inputs like selection and options and entities that produce source replacements , but I could probably get rid of most of RefactoringActionRule template magic.

include/clang/Tooling/Refactoring/SourceSelectionConstraints.h

42

Oops, this isn't supposed to be in this patch, I will remove.

test/Refactor/LocalRename/Field.cpp

4

I thought I should check for occurrences, but you're right, it's probably better to always check the source replacements (we can introduce options that apply non-default occurrences in the future which would allow us to check replacements for occurrences in comments).

Would something like //CHECK: "newName" [[@LINE]]:24 -> [[]]:27 work when checking for replacements?

tools/clang-refactor/ClangRefactor.cpp

61

Not from my experience, I've tried multiple actions it seems like the right arguments are parsed for the right subcommand. It looks like the cl option parser looks is smart enough to handle identical options across multiple subcommands.

313

I don't quite follow, when would multiple subcommands be satisfied? The subcommand corresponds to the action that the user wants to do, there should be no ambiguity.

[klimek]

test/Refactor/LocalRename/Field.cpp

4

Yep, I think that'd be better.
Or we could just apply the replacement and check on the replaced code? (I think that's what we do in fixits for clang and clang-tidy)

[arphaman]

• Test by checking the modified source directly. This allowed me to get rid of the refactoring result wrapper as well.
• Remove ASTRefactoringContext
• Address the other review comments

[arphaman]

tools/clang-refactor/ClangRefactor.cpp

61

I agree that using CommonOptionsParser would be preferable, but right now it doesn't work well with subcommands. I will create a followup patch that improves subcommand support in CommonOptionsParser and uses them in clang-refactor when this patch is accepted.

[ioeric]

include/clang/Tooling/Refactoring/RefactoringActionRules.h

45

Can we get rid of this overload and simply make RefactoringRuleContext mandatory for all refactoring functions?

include/clang/Tooling/Refactoring/RefactoringActionRulesInternal.h

99

Do we still need this overload?

include/clang/Tooling/Refactoring/RefactoringRuleContext.h

56

Should we also provide an interface to test if this has an ASTContext? Or maybe simply return null if there is ASTContext? WDYT?

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

97

Should this be private?

tools/clang-refactor/ClangRefactor.cpp

61

Thanks! Could you add a FIXME for the CommonOptionsParser change?

313

(I added this comment a while ago, and it seemed to have shifted. I was intended to comment on line 297 auto It = llvm::find_if(. Sorry about that.)

I guess I don't quite understand how a specific subcommand is picked based on the commandline options users provide. The llvm::find_if above seems to simply find the first action/subcommand that is registered? Could you add a comment about how submamands are matched?

[arphaman]

• Always pass in RefactoringRuleContext to the refactoring rule's function.
• Remove now redundant overloads.
• Make LocalRename's actions members private.
• Add CommandLienParser FIXME comment.
• Verify that refactoring actions have unique command names.
• Add a comment that explains how a subcommand is selected.

include/clang/Tooling/Refactoring/RefactoringActionRulesInternal.h

99

Removed.

tools/clang-refactor/ClangRefactor.cpp

61

Done.

313

Ah, I see.

I added a comment in the updated patch that tries to explain the process. Basically we know that one action maps to just one subcommand because the actions must have unique command names. Since we've already created the subcommands, LLVM's command-line parser enables one particular subcommand that was specified in the command-line arguments. This is what this search does, we just look for the enabled subcommand that was turned on by LLVM's command-line parser, without taking any other command-line arguments into account.

[ioeric]

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

90

Shouldn't these be public?

tools/clang-refactor/ClangRefactor.cpp

80

Why return a mutable reference? Also, this is not used in this patch; maybe leave it out?

104

Is the test selection temporary before we have true selection?

I am a bit concerned about having test logic in the production code. It makes the code paths a bit complicated, and we might easily end up testing the test logic instead of the actual code logic. I'm fine with this if this is just a short term solution before we have the actual selection support.

313

Ohh! I didn't notice RefactoringActionSubcommand inherits cl::SubCommand. Thanks for the explanation!

tools/clang-refactor/TestSupport.cpp

188

I think the ...In suffix is redundant. We could either get rid of it or use ...InFile.

[arphaman]

tools/clang-refactor/ClangRefactor.cpp

104

No, both are meant to co-exist. I guess we could introduce a new option (-selection vs -test-selection and hide -test-selection)? Another approach that I was thinking about is to have a special hidden subcommand for each action (e.g. test-local-rename). Alternatively we could use two different tools (clang-refactor vs clang-refactor-test)? Both will have very similar code though.

Note that it's not the first time test logic will exist in the final tool. For example, llvm-cov has a convert-for-testing subcommand that exists in the production tool. I'm not saying that it's necessarily the best option though, but I don't think it's the worst one either ;)

[arphaman]

Address review comments

[ioeric]

tools/clang-refactor/ClangRefactor.cpp

104

I guess I am more concerned about mixing production code with testing code than having special options. For example, we have different invocation paths based on ParsedTestSelection. IMO, whether selected ranges come from test selection or actual selection should be transparent to clang-refactor. Maybe refactoring the selection handling logic out as a separate interface would help?

[arphaman]

Refactor the selection argument handling by using a SourceSelectionArgument interface with subclass for test selection and separate out the test code from the tool class.

[arphaman]

tools/clang-refactor/ClangRefactor.cpp

80

Removed.

104

Makes sense, I just did a cleanup refactoring that should make it better.

[ioeric]

tools/clang-refactor/ClangRefactor.cpp

30

Sorry for haven't noticed this earlier, but I think clang::refactor sounds like a better name space than clang::clang_refactor.

63

I would expect the SourceSelectionArgument to be more like a container of ranges and further decoupled with the refactoring logic. Same for the TestSelectionRangesInFile.

How about an interface like this?

template <typename T>
void ForAllRanges(T callback) const;

65

Do we want to consider other result types?

[arphaman]

• rename namespace
• try to further decouple SourceSelectionArgument

[arphaman]

tools/clang-refactor/ClangRefactor.cpp

63

Not sure I fully understand your interface suggestion, but I've tried to decouple some more in the updated patch.

[ioeric]

I think this is ready to go.

@klimek Manuel, are all your concerns addressed?

tools/clang-refactor/ClangRefactor.cpp

63

Sorry, I should've been more specific about what I had in mind, but what you have right now is close. I think this can be further decoupled a bit by having forAllRanges take in SourceManeger instead of RefactoringRuleContext since source selection should only care about source ranges.

63

IIUC, createCustomConsumer is used to inject testing behavior into clang-refactor. I think this is fine, but please document the intention and the behavior. Thanks!

[ioeric]

Please wait for Manuel's reply before landing the patch ;-)

[arphaman]

@klimek I've added a patch that simplifies the interface and the template code - https://reviews.llvm.org/D37681. Hopefully you'll find that the code there is cleaner.

[ioeric]

Feel free to land the patch now if comments are addressed.

[klimek]

LG. Nice, thanks!

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

89

I have to admit, the implementation here is pretty neat! :)

[hokein]

LGTM, a few nits.

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

89

+1

test/Refactor/LocalRename/Field.cpp

5

I'd use a completed statement in CHECK (like int /*range=*/Bar;), which is more obvious to readers.

test/Refactor/tool-test-support.c

30

Maybe add a comment describing the following cases are named test group -- it took me a while to understand why these "invoking action" messages aren't ordered by the original source line number.

tools/clang-refactor/ClangRefactor.cpp

90

nit: virtual isn't needed.

tools/clang-refactor/TestSupport.cpp

29

I'm not a big fan of using namespace. It would make it hard to find out which namespace is the following method in -- readers have to go to the corresponding header file to find out the namespace. I'm +1 on using a more regular way namespace clang { namespace refactor {...} }.

128

nit: virtual can be removed, the same below.

tools/clang-refactor/TestSupport.h

33

Do you plan to use refactor on other files?

105

s/clang_refactor/refactor

[arphaman]

Oops, I've put in the wrong diff link for r313025. This patch is still not committed.

[arphaman]

tools/clang-refactor/TestSupport.h

33

Probably in the future, yeah.

[hokein]

Seems that you have attached a wrong diff, which is committed in r313025.

tools/clang-refactor/TestSupport.h

33

SG.

[arphaman]

Yeah, I accidentally committed a prior patch with the link to this diff. I will commit this patch today though so it should be updated.

include/clang/Tooling/Refactoring/RefactoringAction.h

+//===--- RefactoringAction.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_H
+#define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_H
+
+#include "clang/Basic/LLVM.h"
+#include "clang/Tooling/Refactoring/RefactoringActionRules.h"
+#include <vector>
+
+namespace clang {
+namespace tooling {
+
+class RefactoringAction {
+public:
+  /// Returns the name of the subcommand that's used by clang-refactor for this
+  /// action.
+  virtual StringRef getCommand() const = 0;
+
+  virtual StringRef getDescription() const = 0;
+
+  /// Returns a set of refactoring actions rules that are defined by this
+  /// action.
+  virtual RefactoringActionRules createActionRules() const = 0;
+
+  virtual ~RefactoringAction() {}
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_H

include/clang/Tooling/Refactoring/RefactoringActionRegistry.def

+#ifndef REFACTORING_ACTION
+#define REFACTORING_ACTION(Name)
+#endif
+
+REFACTORING_ACTION(LocalRename)
+
+#undef REFACTORING_ACTION

include/clang/Tooling/Refactoring/RefactoringActionRule.h

public:
   virtual ~RefactoringActionRule() {}
 
   /// Initiates and performs a specific refactoring action.
   ///
   /// The specific rule will invoke an appropriate \c handle method on a
   /// consumer to propagate the result of the refactoring action.
   virtual void invoke(RefactoringResultConsumer &Consumer,
                       RefactoringRuleContext &Context) = 0;
+
+  /// Returns true when the rule has a source selection requirement that has
+  /// to be fullfilled before refactoring can be performed.
+  virtual bool hasSelectionRequirement() = 0;
 };
 
 /// A set of refactoring action rules that should have unique initiation
 /// requirements.
 using RefactoringActionRules =
     std::vector<std::unique_ptr<RefactoringActionRule>>;
 
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULE_H

include/clang/Tooling/Refactoring/RefactoringActionRuleRequirementsInternal.h

struct SourceSelectionRequirement
   /// an OutputT if the selection requirement was successfully. The OutpuT
   /// value is wrapped in Expected<Optional<>> which is then unwrapped by the
   /// refactoring action rule before passing the value to the refactoring
   /// function.
   Expected<Optional<OutputType>> evaluate(RefactoringRuleContext &Context) {
     Optional<InputT> Value = InputT::evaluate(Context);
     if (!Value)
       return None;
-    return std::move(Requirement.evaluateSelection(*Value));
+    return std::move(
+        selection::traits::EvaluteRequirement<RequirementT>::evaluateSelection(
+            Requirement, Context, *Value));
   }
 
 private:
   const RequirementT Requirement;
 };
 
 } // end namespace internal
 
 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<internal::RequirementBase, T>::value,
                        std::true_type, std::false_type>::type {};
 
+/// A type trait that returns true when the given type has at least one source
+/// selection requirement.
+template <typename First, typename... Rest>
+struct HasSelectionRequirement
+    : std::conditional<HasSelectionRequirement<First>::value ||
+                           HasSelectionRequirement<Rest...>::value,
+                       std::true_type, std::false_type>::type {};
+
+template <typename I, typename O, typename R>
+struct HasSelectionRequirement<internal::SourceSelectionRequirement<I, O, R>>
+    : std::true_type {};
+
+template <typename T> struct HasSelectionRequirement<T> : std::false_type {};
+
 } // end namespace traits
 } // end namespace refactoring_action_rules
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_REQUIREMENTS_INTERNAL_H

include/clang/Tooling/Refactoring/RefactoringActionRules.h

 #ifndef LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H
 #define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H
 
 #include "clang/Tooling/Refactoring/RefactoringActionRule.h"
 #include "clang/Tooling/Refactoring/RefactoringActionRulesInternal.h"
 
 namespace clang {
 namespace tooling {
+
+class ASTRefactoringContext;
+
 namespace refactoring_action_rules {
 
 /// 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. The function must return a valid
 /// refactoring result type wrapped in an \c Expected type. The following result
 /// types are currently supported:
 ///
 ///  - AtomicChanges: the refactoring function will be used to create source
 ///                   replacements.
 ///
 /// \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 ResultType, typename... RequirementTypes>
 std::unique_ptr<RefactoringActionRule>
 createRefactoringRule(Expected<ResultType> (*RefactoringFunction)(
                           typename RequirementTypes::OutputType...),
                       const RequirementTypes &... Requirements) {
   static_assert(tooling::traits::IsValidRefactoringResult<ResultType>::value,
                 "invalid refactoring result type");
   static_assert(traits::IsRequirement<RequirementTypes...>::value,
                 "invalid refactoring action rule requirement");
   return llvm::make_unique<internal::PlainFunctionRule<
-      decltype(RefactoringFunction), RequirementTypes...>>(
+      decltype(RefactoringFunction), /*SpecificContextType=*/void,
+      RequirementTypes...>>(RefactoringFunction,
+                            std::make_tuple(Requirements...));
+}
+
+template <typename ResultType, typename... RequirementTypes>
+std::unique_ptr<RefactoringActionRule>
+createRefactoringRule(Expected<ResultType> (*RefactoringFunction)(
+                          const ASTRefactoringContext &,
+                          typename RequirementTypes::OutputType...),
+                      const RequirementTypes &... Requirements) {
+  static_assert(tooling::traits::IsValidRefactoringResult<ResultType>::value,
+                "invalid refactoring result type");
+  static_assert(traits::IsRequirement<RequirementTypes...>::value,
+                "invalid refactoring action rule requirement");
+  return llvm::make_unique<internal::PlainFunctionRule<
+      decltype(RefactoringFunction),
+      /*SpecificContextType=*/ASTRefactoringContext, RequirementTypes...>>(
       RefactoringFunction, std::make_tuple(Requirements...));
 }
 
 template <
     typename Callable, typename... RequirementTypes,
     typename Fn = decltype(&Callable::operator()),
     typename ResultType = typename internal::LambdaDeducer<Fn>::ReturnType,
     bool IsNonCapturingLambda = std::is_convertible<
-        Callable,
-        ResultType (*)(typename RequirementTypes::OutputType...)>::value,
+        Callable, typename internal::LambdaDeducer<Fn>::FunctionType>::value,
     typename = typename std::enable_if<IsNonCapturingLambda>::type>
 std::unique_ptr<RefactoringActionRule>
 createRefactoringRule(const Callable &C,
                       const RequirementTypes &... Requirements) {
-  ResultType (*Func)(typename RequirementTypes::OutputType...) = C;
+  typename internal::LambdaDeducer<Fn>::FunctionType Func = C;
   return createRefactoringRule(Func, Requirements...);
 }
 
 } // end namespace refactoring_action_rules
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_H

include/clang/Tooling/Refactoring/RefactoringActionRulesInternal.h

 namespace clang {
 namespace tooling {
 namespace refactoring_action_rules {
 namespace internal {
 
 /// 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>
+template <typename FunctionType, typename SpecificContextType,
+          typename... RequirementTypes>
 class PlainFunctionRule final : public RefactoringActionRule {
 public:
   PlainFunctionRule(FunctionType Function,
                     std::tuple<RequirementTypes...> &&Requirements)
       : Function(Function), Requirements(std::move(Requirements)) {}
 
   void invoke(RefactoringResultConsumer &Consumer,
               RefactoringRuleContext &Context) override {
     return invokeImpl(Consumer, Context,
                       llvm::index_sequence_for<RequirementTypes...>());
   }
 
+  bool hasSelectionRequirement() override {
+    return traits::HasSelectionRequirement<RequirementTypes...>::value;
+  }
+
 private:
   /// Returns \c T when given \c Expected<Optional<T>>, or \c T otherwise.
   template <typename T>
   static T &&unwrapRequirementResult(Expected<Optional<T>> &&X) {
     assert(X && "unexpected diagnostic!");
     return std::move(**X);
   }
   template <typename T> static T &&unwrapRequirementResult(T &&X) {
private:
   static Optional<llvm::Error> takeErrorNone(Expected<Optional<T>> &Diag) {
     if (!Diag)
       return std::move(Diag.takeError());
     if (!*Diag)
       return llvm::Error::success(); // Initiation failed without a diagnostic.
     return None;
   }
 
+  template <typename ContextType, typename ValueType, size_t... Is>
+  void invokeImplDispatch(
+      RefactoringResultConsumer &Consumer, RefactoringRuleContext &Context,
+      llvm::index_sequence<Is...>, ValueType &Values,
+      typename std::enable_if<
+          std::is_same<ContextType, ASTRefactoringContext>::value>::type * =
+          nullptr) {
+    auto Result =
+        Function(Context.getSpecificRuleContext<ContextType>(),
+                 unwrapRequirementResult(std::move(std::get<Is>(Values)))...);
+    if (!Result)
+      return Consumer.handleError(Result.takeError());
+    Consumer.handle(std::move(*Result));
+  }
+
+  template <typename ContextType, typename ValueType, size_t... Is>
+  void invokeImplDispatch(
+      RefactoringResultConsumer &Consumer, RefactoringRuleContext &,
+      llvm::index_sequence<Is...>, ValueType &Values,
+      typename std::enable_if<std::is_same<ContextType, void>::value>::type * =
+          nullptr) {
+    auto Result =
+        Function(unwrapRequirementResult(std::move(std::get<Is>(Values)))...);
+    if (!Result)
+      return Consumer.handleError(Result.takeError());
+    Consumer.handle(std::move(*Result));
+  }
+
   template <size_t... Is>
   void invokeImpl(RefactoringResultConsumer &Consumer,
                   RefactoringRuleContext &Context,
-                  llvm::index_sequence<Is...>) {
+                  llvm::index_sequence<Is...> Seq) {
     // Initiate the operation.
     auto Values =
         std::make_tuple(std::get<Is>(Requirements).evaluate(Context)...);
     Optional<llvm::Error> InitiationFailure =
         findErrorNone(std::get<Is>(Values)...);
     if (InitiationFailure) {
       llvm::Error Error = std::move(*InitiationFailure);
       if (!Error)
         // FIXME: Use a diagnostic.
         return Consumer.handleError(llvm::make_error<llvm::StringError>(
             "refactoring action can't be initiated with the specified "
             "selection range",
             llvm::inconvertibleErrorCode()));
       return Consumer.handleError(std::move(Error));
     }
     // Perform the operation.
-    auto Result =
-        Function(unwrapRequirementResult(std::move(std::get<Is>(Values)))...);
-    if (!Result)
-      return Consumer.handleError(Result.takeError());
-    Consumer.handle(std::move(*Result));
+    invokeImplDispatch<SpecificContextType, decltype(Values), Is...>(
+        Consumer, Context, Seq, Values);
   }
 
   FunctionType Function;
   std::tuple<RequirementTypes...> Requirements;
 };
 
 /// Used to deduce the refactoring result type for the lambda that passed into
 /// createRefactoringRule.
 template <typename T> struct LambdaDeducer;
 template <typename T, typename R, typename... Args>
 struct LambdaDeducer<R (T::*)(Args...) const> {
   using ReturnType = R;
+  using FunctionType = R (*)(Args...);
+};
+template <typename T, typename R, typename... Args>
+struct LambdaDeducer<R (T::*)(const ASTRefactoringContext &, Args...) const> {
+  using ReturnType = R;
+  using FunctionType = R (*)(const ASTRefactoringContext &, Args...);
 };
 
 } // end namespace internal
 } // end namespace refactoring_action_rules
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ACTION_RULES_INTERNAL_H

include/clang/Tooling/Refactoring/RefactoringEngine.h

+//===--- RefactoringEngine.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_ENGINE_H
+#define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ENGINE_H
+
+#include "clang/Tooling/Refactoring/RefactoringAction.h"
+#include "clang/Tooling/Refactoring/RefactoringActionRules.h"
+#include "llvm/ADT/DenseMap.h"
+#include <vector>
+
+namespace clang {
+namespace tooling {
+
+/// A base class for an editor or a tool refactoring engine.
+///
+/// Contains the list of supported actions and refactoring action rules.
+class RefactoringEngine {
+public:
+  virtual ~RefactoringEngine() {}
+
+  virtual void initialize();
+
+protected:
+  struct ActionState {
+    RefactoringActionRules Rules;
+  };
+
+  std::vector<std::unique_ptr<RefactoringAction>> Actions;
+  llvm::DenseMap<const RefactoringAction *, ActionState> State;
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_ENGINE_H

include/clang/Tooling/Refactoring/RefactoringRuleContext.h

 //===--- RefactoringRuleContext.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_RULE_CONTEXT_H
 #define LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_RULE_CONTEXT_H
 
 #include "clang/Basic/SourceManager.h"
 
 namespace clang {
+
+class ASTContext;
+
 namespace tooling {
 
+/// A refactoring rule context that's available to the refactoring rules that
+/// require the AST.
+class ASTRefactoringContext {
+public:
+  ASTRefactoringContext(ASTContext &Context) : Context(Context) {}
+
+  ASTContext &getASTContext() const { return Context; }
+
+private:
+  ASTContext &Context;
+};
+
 /// The refactoring rule context stores all of the inputs that might be needed
 /// by a refactoring action rule. It can create the specialized
 /// \c ASTRefactoringOperation or \c PreprocessorRefactoringOperation values
 /// that can be used by the refactoring action rules.
 ///
 /// The following inputs are stored by the operation:
 ///
 ///   - SourceManager: a reference to a valid source manager.
 ///
 ///   - SelectionRange: an optional source selection ranges that can be used
 ///     to represent a selection in an editor.
 class RefactoringRuleContext {
 public:
   RefactoringRuleContext(const SourceManager &SM) : SM(SM) {}
 
   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; }
 
+  ASTContext *getASTContext() const { return AST; }
+
+  void setASTContext(ASTContext &Context) { AST = &Context; }
+
+  /// Returns a specific refactoring rule context like \c ASTRefactoringContext.
+  template <typename T> T getSpecificRuleContext();
+
 private:
   /// The source manager for the translation unit / file on which a refactoring
   /// action might operate on.
   const SourceManager &SM;
   /// An optional source selection range that's commonly used to represent
   /// a selection in an editor.
   SourceRange SelectionRange;
+  /// An optional AST for the translation unit on which a refactoring action
+  /// might operate on.
+  ASTContext *AST = nullptr;
 };
 
+template <>
+inline ASTRefactoringContext RefactoringRuleContext::getSpecificRuleContext() {
+  assert(AST && "can't create an ASTRefactoringContext without AST");
+  return ASTRefactoringContext(*AST);
+}
+
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_REFACTORING_RULE_CONTEXT_H

include/clang/Tooling/Refactoring/Rename/SymbolOccurrences.h

public:
   ArrayRef<SourceRange> getNameRanges() const {
     if (MultipleRanges) {
       return llvm::makeArrayRef(MultipleRanges.get(),
                                 RangeOrNumRanges.getBegin().getRawEncoding());
     }
     return RangeOrNumRanges;
   }
 
+  bool operator==(const SymbolOccurrence &Other) const {
+    if (Kind != Other.Kind)
+      return false;
+    if (getNameRanges().size() != Other.getNameRanges().size())
+      return false;
+    for (size_t I = 0, E = getNameRanges().size(); I != E; ++I) {
+      if (getNameRanges()[I] != Other.getNameRanges()[I])
+        return false;
+    }
+    return true;
+  }
+
 private:
   OccurrenceKind Kind;
   std::unique_ptr<SourceRange[]> MultipleRanges;
   SourceRange RangeOrNumRanges;
 };
 
 using SymbolOccurrences = std::vector<SymbolOccurrence>;
 
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_OCCURRENCES_H

include/clang/Tooling/Refactoring/Rename/USRFindingAction.h

 #include "clang/Basic/LLVM.h"
 #include "llvm/ADT/ArrayRef.h"
 
 #include <string>
 #include <vector>
 
 namespace clang {
 class ASTConsumer;
+class ASTContext;
 class CompilerInstance;
 class NamedDecl;
 
 namespace tooling {
 
 /// Returns the canonical declaration that best represents a symbol that can be
 /// renamed.
 ///
 /// The following canonicalization rules are currently used:
 ///
 /// - A constructor is canonicalized to its class.
 /// - A destructor is canonicalized to its class.
 const NamedDecl *getCanonicalSymbolDeclaration(const NamedDecl *FoundDecl);
 
+/// Returns the set of USRs that correspond to the given declaration.
+std::vector<std::string> getUSRsForDeclaration(const NamedDecl *ND,
+                                               ASTContext &Context);
+
 struct USRFindingAction {
   USRFindingAction(ArrayRef<unsigned> SymbolOffsets,
                    ArrayRef<std::string> QualifiedNames, bool Force)
       : SymbolOffsets(SymbolOffsets), QualifiedNames(QualifiedNames),
         ErrorOccurred(false), Force(Force) {}
   std::unique_ptr<ASTConsumer> newASTConsumer();
 
   ArrayRef<std::string> getUSRSpellings() { return SpellingNames; }

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/LLVM.h"
 #include "clang/Basic/SourceLocation.h"
+#include "clang/Tooling/Refactoring/RefactoringRuleContext.h"
 #include <type_traits>
 
 namespace clang {
 namespace tooling {
 
 class RefactoringRuleContext;
 
 namespace selection {
struct SourceSelectionRange {
   static Optional<SourceSelectionRange>
   evaluate(RefactoringRuleContext &Context);
 
 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.
+  /// or 'T evaluateSelection(const ASTRefactoringContext &,
+  /// 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 internal {
 
 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;
+
+  static R evaluateSelection(const T &Requirement, RefactoringRuleContext &,
+                             A Input) {
+    return Requirement.evaluateSelection(Input);
+  }
+};
+
+template <typename T, typename R, typename A>
+struct EvaluateSelectionChecker<R (T::*)(const ASTRefactoringContext &, A)
+                                    const> : std::true_type {
+  using ReturnType = R;
+  using ArgType = A;
+
+  static R evaluateSelection(const T &Requirement,
+                             RefactoringRuleContext &Context, A Input) {
+    return Requirement.evaluateSelection(
+        Context.getSpecificRuleContext<ASTRefactoringContext>(), Input);
+  }
 };
 
 template <typename T> class Identity : public Requirement {
 public:
   T evaluateSelection(T Value) const { return std::move(Value); }
 };
 
 } // end namespace internal
struct IsRequirement
     : std::conditional<
           std::is_base_of<Requirement, T>::value &&
               internal::EvaluateSelectionChecker<decltype(
                   &T::evaluateSelection)>::value &&
               IsConstraint<typename internal::EvaluateSelectionChecker<decltype(
                   &T::evaluateSelection)>::ArgType>::value,
           std::true_type, std::false_type>::type {};
 
+/// Declares an \c evaluateSelection static function that calls the corrept
+/// \c evaluateSelection method in the requirement.
+template <typename T>
+struct EvaluteRequirement
+    : internal::EvaluateSelectionChecker<decltype(&T::evaluateSelection)> {
+  using internal::EvaluateSelectionChecker<decltype(
+      &T::evaluateSelection)>::evaluateSelection;
+};
+
 } // end namespace traits
 } // end namespace selection
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_SOURCE_SELECTION_CONSTRAINTS_H

include/clang/module.modulemap

 
 module Clang_Tooling {
   requires cplusplus umbrella "Tooling" module * { export * }
   // FIXME: Exclude these headers to avoid pulling all of the AST matchers
   // library into clang-format. Due to inline key functions in the headers,
   // importing the AST matchers library gives a link dependency on the AST
   // matchers (and thus the AST), which clang-format should not have.
   exclude header "Tooling/RefactoringCallbacks.h"
+
+  textual header "Tooling/Refactoring/RefactoringActionRegistry.def"
 }
 
 module Clang_ToolingCore {
   requires cplusplus
   umbrella "Tooling/Core" module * { export * }
 }

lib/Tooling/Refactoring/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS Support)
 
 add_clang_library(clangToolingRefactor
   ASTSelection.cpp
   AtomicChange.cpp
+  RefactoringEngine.cpp
   Rename/RenamingAction.cpp
   Rename/SymbolOccurrences.cpp
   Rename/USRFinder.cpp
   Rename/USRFindingAction.cpp
   Rename/USRLocFinder.cpp
   SourceSelectionConstraints.cpp
 
   LINK_LIBS
   clangAST
   clangASTMatchers
   clangBasic
   clangFormat
   clangIndex
   clangLex
   clangToolingCore
   )

lib/Tooling/Refactoring/RefactoringEngine.cpp

+//===--- RefactoringEngine.cpp - Common refactoring engine code -----------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "clang/Tooling/Refactoring/RefactoringEngine.h"
+#include "clang/Basic/SourceManager.h"
+#include "llvm/ADT/STLExtras.h"
+
+namespace clang {
+namespace tooling {
+
+// Forward declare the individual create*Action functions.
+#define REFACTORING_ACTION(Name)                                               \
+  std::unique_ptr<RefactoringAction> create##Name##Action();
+#include "clang/Tooling/Refactoring/RefactoringActionRegistry.def"
+
+} // end namespace tooling
+} // end namespace clang
+
+using namespace clang;
+using namespace tooling;
+
+void RefactoringEngine::initialize() {
+// Create the refactoring action.
+#define REFACTORING_ACTION(Name) Actions.push_back(create##Name##Action());
+#include "clang/Tooling/Refactoring/RefactoringActionRegistry.def"
+
+  // Create the refactoring action rules.
+  for (const auto &Action : Actions) {
+    RefactoringActionRules Rules = Action->createActionRules();
+    // FIXME (Alex L): Drop unsupported rules.
+    State[Action.get()].Rules = std::move(Rules);
+  }
+}

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

 #include "clang/AST/ASTContext.h"
 #include "clang/Basic/FileManager.h"
 #include "clang/Frontend/CompilerInstance.h"
 #include "clang/Frontend/FrontendAction.h"
 #include "clang/Lex/Lexer.h"
 #include "clang/Lex/Preprocessor.h"
 #include "clang/Tooling/CommonOptionsParser.h"
 #include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Refactoring/RefactoringAction.h"
+#include "clang/Tooling/Refactoring/RefactoringActionRules.h"
+#include "clang/Tooling/Refactoring/Rename/USRFinder.h"
+#include "clang/Tooling/Refactoring/Rename/USRFindingAction.h"
 #include "clang/Tooling/Refactoring/Rename/USRLocFinder.h"
 #include "clang/Tooling/Tooling.h"
 #include "llvm/ADT/STLExtras.h"
 #include <string>
 #include <vector>
 
 using namespace llvm;
+using namespace clang;
+using namespace tooling;
+
+namespace {
+
+class LocalRename : public RefactoringAction {
+public:
+  StringRef getCommand() const override { return "local-rename"; }
+
+  StringRef getDescription() const override {
+    return "Finds and renames symbols in code with no indexer support";
+  }
+
+  static Expected<SymbolOccurrences>
+  findOccurrences(const ASTRefactoringContext &Context, const NamedDecl *ND) {
+    std::vector<std::string> USRs =
+        getUSRsForDeclaration(ND, Context.getASTContext());
+    std::string PrevName = ND->getNameAsString();
+    return getOccurrencesOfUSRs(
+        USRs, PrevName, Context.getASTContext().getTranslationUnitDecl());
+  }
+
+  class SymbolSelectionRequirement : public selection::Requirement {
+  public:
+    Expected<Optional<const NamedDecl *>>
+    evaluateSelection(const ASTRefactoringContext &Context,
+                      selection::SourceSelectionRange Selection) const {
+      const NamedDecl *ND = getNamedDeclAt(Context.getASTContext(),
+                                           Selection.getRange().getBegin());
+      if (!ND)
+        return None;
+      return getCanonicalSymbolDeclaration(ND);
+    }
+  };
+
+  /// Returns a set of refactoring actions rules that are defined by this
+  /// action.
+  RefactoringActionRules createActionRules() const override {
+    using namespace refactoring_action_rules;
+    RefactoringActionRules Rules;
+    Rules.push_back(createRefactoringRule(
+        findOccurrences, requiredSelection(SymbolSelectionRequirement())));
+    return Rules;
+  }
+};
+
+} // end anonymous namespace
 
 namespace clang {
 namespace tooling {
 
+std::unique_ptr<RefactoringAction> createLocalRenameAction() {
+  return llvm::make_unique<LocalRename>();
+}
+
 Expected<std::vector<AtomicChange>>
 createRenameReplacements(const SymbolOccurrences &Occurrences,
                          const SourceManager &SM,
                          ArrayRef<StringRef> NewNameStrings) {
   // FIXME: A true local rename can use just one AtomicChange.
   std::vector<AtomicChange> Changes;
   for (const auto &Occurrence : Occurrences) {
     ArrayRef<SourceRange> Ranges = Occurrence.getNameRanges();
     assert(NewNameStrings.size() == Ranges.size() &&
            "Mismatching number of ranges and name pieces");
     AtomicChange Change(SM, Ranges[0].getBegin());
     for (const auto &Range : llvm::enumerate(Ranges)) {
       auto Error =
           Change.replace(SM, CharSourceRange::getCharRange(Range.value()),
                          NewNameStrings[Range.index()]);

lib/Tooling/Refactoring/Rename/USRFindingAction.cpp

private:
   const Decl *FoundDecl;
   ASTContext &Context;
   std::set<std::string> USRSet;
   std::vector<const CXXMethodDecl *> OverriddenMethods;
   std::vector<const ClassTemplatePartialSpecializationDecl *> PartialSpecs;
 };
 } // namespace
 
+std::vector<std::string> getUSRsForDeclaration(const NamedDecl *ND,
+                                               ASTContext &Context) {
+  AdditionalUSRFinder Finder(ND, Context);
+  return Finder.Find();
+}
+
 class NamedDeclFindingConsumer : public ASTConsumer {
 public:
   NamedDeclFindingConsumer(ArrayRef<unsigned> SymbolOffsets,
                            ArrayRef<std::string> QualifiedNames,
                            std::vector<std::string> &SpellingNames,
                            std::vector<std::vector<std::string>> &USRList,
                            bool Force, bool &ErrorOccurred)
       : SymbolOffsets(SymbolOffsets), QualifiedNames(QualifiedNames),

test/CMakeLists.txt

 list(APPEND CLANG_TEST_DEPS
   clang clang-headers
   clang-format
   c-index-test diagtool
   clang-tblgen
   clang-offload-bundler
   clang-import-test
   clang-rename
+  clang-refactor
   clang-diff
   )
   
 if(CLANG_ENABLE_STATIC_ANALYZER)
   list(APPEND CLANG_TEST_DEPS
     clang-check
     )
 endif()

test/Refactor/LocalRename/Field.cpp

+// RUN: clang-refactor local-rename -selection=test:%s -no-dbs -dump %s | FileCheck %s
+
+class Baz {
+  int /*range=*/Foo; // CHECK: symbol [[@LINE]]:17 -> [[@LINE]]:20
+public:
+  Baz();
+};
+
+Baz::Baz() : /*range=*/Foo(0) {}  // CHECK: symbol [[@LINE]]:24 -> [[@LINE]]:27

test/Refactor/tool-common-options.c

+// RUN: not clang-refactor 2>&1 | FileCheck --check-prefix=MISSING_ACTION %s
+// MISSING_ACTION: error: no refactoring action given
+// MISSING_ACTION-NEXT: note: the following actions are supported:
+
+// RUN: not clang-refactor local-rename -no-dbs 2>&1 | FileCheck --check-prefix=MISSING_SOURCES %s
+// MISSING_SOURCES: error: must provide paths to the source files when '-no-dbs' is used

test/Refactor/tool-test-support.c

+// RUN: clang-refactor local-rename -selection=test:%s -no-dbs -dump -v %s 2>&1 | FileCheck %s
+
+/*range=*/int test;
+
+/*range named=*/int test2;
+
+/*range= +1*/int test3;
+
+/* range = +100 */int test4;
+
+/*range named =+0*/int test5;
+
+// CHECK: Test selection group '':
+// CHECK-NEXT:   106-106
+// CHECK-NEXT:   159-159
+// CHECK-NEXT:   198-198
+// CHECK-NEXT: Test selection group 'named':
+// CHECK-NEXT:   133-133
+// CHECK-NEXT:   219-219
+
+// CHECK: invoking action 'local-rename':
+// CHECK-NEXT: -selection={{.*}}tool-test-support.c:3:11
+
+// CHECK: invoking action 'local-rename':
+// CHECK-NEXT: -selection={{.*}}tool-test-support.c:7:15
+
+// CHECK: invoking action 'local-rename':
+// CHECK-NEXT: -selection={{.*}}tool-test-support.c:9:29
+
+// CHECK: invoking action 'local-rename':
+// CHECK-NEXT: -selection={{.*}}tool-test-support.c:5:17
+
+// CHECK: invoking action 'local-rename':
+// CHECK-NEXT: -selection={{.*}}tool-test-support.c:11:20

test/clang-rename/Field.cpp

-class Baz {
-  int Foo; /* Test 1 */ // CHECK: int Bar;
-public:
-  Baz();
-};
-
-Baz::Baz() : Foo(0) /* Test 2 */ {}  // CHECK: Baz::Baz() : Bar(0)
-
-// Test 1.
-// RUN: clang-rename -offset=18 -new-name=Bar %s -- | sed 's,//.*,,' | FileCheck %s
-// Test 2.
-// RUN: clang-rename -offset=89 -new-name=Bar %s -- | sed 's,//.*,,' | FileCheck %s
-
-// To find offsets after modifying the file, use:
-//   grep -Ubo 'Foo.*' <file>

tools/CMakeLists.txt

 create_subdirectory_options(CLANG TOOL)
 
 add_clang_subdirectory(diagtool)
 add_clang_subdirectory(driver)
 add_clang_subdirectory(clang-diff)
 add_clang_subdirectory(clang-format)
 add_clang_subdirectory(clang-format-vs)
 add_clang_subdirectory(clang-fuzzer)
 add_clang_subdirectory(clang-import-test)
 add_clang_subdirectory(clang-offload-bundler)
 
 add_clang_subdirectory(c-index-test)
 
 add_clang_subdirectory(clang-rename)
+add_clang_subdirectory(clang-refactor)
 
 if(CLANG_ENABLE_ARCMT)
   add_clang_subdirectory(arcmt-test)
   add_clang_subdirectory(c-arcmt-test)
 endif()
 
 if(CLANG_ENABLE_STATIC_ANALYZER)
   add_clang_subdirectory(clang-check)

tools/clang-refactor/CMakeLists.txt

+set(LLVM_LINK_COMPONENTS
+  Option
+  Support
+  )
+
+add_clang_executable(clang-refactor
+  ClangRefactor.cpp
+  DumpRefactoringResult.cpp
+  TestSupport.cpp
+  )
+
+target_link_libraries(clang-refactor
+  clangBasic
+  clangFrontend
+  clangRewrite
+  clangTooling
+  clangToolingCore
+  clangToolingRefactor
+  )
+
+install(TARGETS clang-refactor RUNTIME DESTINATION bin)

tools/clang-refactor/ClangRefactor.cpp

+//===--- ClangRefactor.cpp - Clang-based refactoring tool -----------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief This file implements a clang-refactor tool that performs various
+/// source transformations.
+///
+//===----------------------------------------------------------------------===//
+
+#include "TestSupport.h"
+#include "clang/Rewrite/Core/Rewriter.h"
+#include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Refactoring/RefactoringEngine.h"
+#include "clang/Tooling/Tooling.h"
+#include "llvm/Support/CommandLine.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/raw_ostream.h"
+#include <string>
+
+using namespace clang;
+using namespace tooling;
+using namespace clang_refactor;
+namespace cl = llvm::cl;
+
+namespace opts {
+
+static cl::OptionCategory CommonRefactorOptions("Common refactoring options");
+
+static cl::opt<bool> DumpResults(
+    "dump",
+    cl::desc("Dump the produced source replacements instead of applying them"),
+    cl::cat(CommonRefactorOptions), cl::sub(*cl::AllSubCommands));
+
+static cl::opt<bool>
+    NoDatabases("no-dbs",
+                cl::desc("Ignore external databases including Clang's "
+                         "compilation database and indexer stores"),
+                cl::cat(CommonRefactorOptions), cl::sub(*cl::AllSubCommands));
+
+static cl::opt<bool> Verbose("v", cl::desc("Use verbose output"),
+                             cl::cat(CommonRefactorOptions),
+                             cl::sub(*cl::AllSubCommands));
+} // end namespace opts
+
+namespace {
+
+/// A subcommand that corresponds to individual refactoring action.
+class RefactoringActionSubcommand : public cl::SubCommand {
+public:
+  RefactoringActionSubcommand(StringRef Name, StringRef Description,
+                              RefactoringAction &Action,
+                              cl::OptionCategory &Category, bool HasSelection)
+      : SubCommand(Name, Description), Action(&Action) {
+    Sources = llvm::make_unique<cl::list<std::string>>(
+        cl::Positional, cl::ZeroOrMore, cl::desc("<source0> [... <sourceN>]"),
+        cl::cat(Category), cl::sub(*this));
+    if (HasSelection) {
+      Selection = llvm::make_unique<cl::opt<std::string>>(
+          "selection", cl::desc("Source selection range"), cl::cat(Category),
+          cl::sub(*this));
+    }
+  }
+
+  ~RefactoringActionSubcommand() { unregisterSubCommand(); }
+
+  RefactoringAction &getAction() const { return *Action; }
+
+  StringRef getSelection() const {
+    assert(Selection && "selection not supported!");
+    return *Selection;
+  }
+
+  /// Returns a pointer to the parsed -selection=find(<filename>) option, or
+  /// null if the selection was given in another format.
+  const TestSelectionRangesInFile *getTestSelection() {
+    parseSelection();
+    return ParsedTestSelection ? ParsedTestSelection.getPointer() : nullptr;
+  }
+
+  ArrayRef<std::string> getSources() const { return *Sources; }
+
+private:
+  void parseSelection() {
+    assert(Selection && "selection not supported!");
+    if (IsSelectionParsed)
+      return;
+    IsSelectionParsed = true;
+    // FIXME: Support true selection ranges.
+    StringRef Value = *Selection;
+    if (Value.startswith("test:")) {
+      StringRef Filename = Value.drop_front(strlen("test:"));
+      ParsedTestSelection = findTestSelectionRangesIn(Filename);
+      if (!ParsedTestSelection) {
+        // A parsing error was already reported.
+        exit(1);
+      }
+    } else {
+      llvm::errs() << "error: '-selection' option must be specified using "
+                      "<file>:<line>:<column> or "
+                      "<file>:<line>:<column>-<line>:<column> format";
+      exit(1);
+    }
+  }
+
+  RefactoringAction *Action;
+  std::unique_ptr<cl::list<std::string>> Sources;
+  std::unique_ptr<cl::opt<std::string>> Selection;
+
+  bool IsSelectionParsed;
+  /// The parsed -selection=test:<filename> option.
+  Optional<TestSelectionRangesInFile> ParsedTestSelection;
+};
+
+/// Wraps the received refactoring results in a \c AbstractRefactoringResult.
+class TestRefactoringResultConsumer final : public RefactoringResultConsumer {
+public:
+  virtual void handleError(llvm::Error Err) override {
+    Result = std::move(Err);
+  }
+
+  virtual void handle(SymbolOccurrences Occurrences) override {
+    Result = llvm::make_unique<RefactoringResultWrapper<SymbolOccurrences>>(
+        std::move(Occurrences));
+  }
+
+  Optional<Expected<std::unique_ptr<AbstractRefactoringResult>>> Result;
+};
+
+class ToolRefactoringEngine final : public RefactoringEngine {
+public:
+  std::vector<std::unique_ptr<RefactoringActionSubcommand>> SubCommands;
+  PartialDiagnostic::StorageAllocator DiagnosticStorage;
+
+  void initialize() override {
+    RefactoringEngine::initialize();
+
+    // Create subcommands and command-line options.
+    for (const auto &Action : Actions) {
+      const ActionState &ActionInfo = State[Action.get()];
+      // Check if the selection option is supported.
+      bool HasSelection = false;
+      for (const auto &Rule : ActionInfo.Rules) {
+        if ((HasSelection = Rule->hasSelectionRequirement()))
+          break;
+      }
+
+      SubCommands.push_back(llvm::make_unique<RefactoringActionSubcommand>(
+          Action->getCommand(), Action->getDescription(), *Action,
+          opts::CommonRefactorOptions, HasSelection));
+    }
+  }
+
+  using TUCallbackType = llvm::function_ref<void(ASTContext &)>;
+
+  /// Parses the translation units that were given to the subcommand using
+  /// the 'sources' option and invokes the callback for each parsed
+  /// translation unit.
+  bool foreachTranslationUnit(RefactoringActionSubcommand &Subcommand,
+                              TUCallbackType Callback) {
+    std::unique_ptr<CompilationDatabase> Compilations;
+    if (opts::NoDatabases) {
+      // FIXME (Alex L): Support compilation options.
+      Compilations =
+          llvm::make_unique<clang::tooling::FixedCompilationDatabase>(
+              ".", std::vector<std::string>());
+    } else {
+      // FIXME (Alex L): Support compilation database.
+      llvm::errs() << "compilation databases are not supported yet!\n";
+      return true;
+    }
+
+    class ToolASTConsumer : public ASTConsumer {
+    public:
+      TUCallbackType Callback;
+      ToolASTConsumer(TUCallbackType Callback) : Callback(Callback) {}
+
+      void HandleTranslationUnit(ASTContext &Context) override {
+        Callback(Context);
+      }
+    };
+    class ActionWrapper {
+    public:
+      TUCallbackType Callback;
+      ActionWrapper(TUCallbackType Callback) : Callback(Callback) {}
+
+      std::unique_ptr<ASTConsumer> newASTConsumer() {
+        return llvm::make_unique<ToolASTConsumer>(std::move(Callback));
+      }
+    };
+
+    ClangTool Tool(*Compilations, Subcommand.getSources());
+    ActionWrapper ToolAction(std::move(Callback));
+    std::unique_ptr<tooling::FrontendActionFactory> Factory =
+        tooling::newFrontendActionFactory(&ToolAction);
+    return Tool.run(Factory.get());
+  }
+
+  /// Logs an individual refactoring action invocation to STDOUT.
+  void logInvocation(RefactoringActionSubcommand &Subcommand,
+                     const RefactoringRuleContext &Context) {
+    if (!opts::Verbose)
+      return;
+    llvm::outs() << "invoking action '" << Subcommand.getName() << "':\n";
+    if (Context.getSelectionRange().isValid()) {
+      SourceRange R = Context.getSelectionRange();
+      llvm::outs() << "  -selection=";
+      R.getBegin().print(llvm::outs(), Context.getSources());
+      llvm::outs() << " -> ";
+      R.getEnd().print(llvm::outs(), Context.getSources());
+      llvm::outs() << "\n";
+    }
+  }
+
+  /// Testing support: invokes the selection action for each selection range in
+  /// the test file.
+  bool
+  runSelectionTestInvocations(RefactoringActionSubcommand &Subcommand,
+                              RefactoringRuleContext &Context,
+                              const TestSelectionRangesInFile &TestSelections,
+                              ArrayRef<RefactoringActionRule *> MatchingRules) {
+    if (opts::Verbose)
+      TestSelections.dump(llvm::outs());
+    if (!opts::DumpResults) {
+      llvm::errs() << "error: test refactoring results can't be applied."
+                      " Did you forget -dump?\n";
+      return true;
+    }
+    return TestSelections.dispatch(
+        Context.getSources(),
+        [&](SourceRange R)
+            -> Expected<std::unique_ptr<AbstractRefactoringResult>> {
+          Context.setSelectionRange(R);
+          logInvocation(Subcommand, Context);
+          for (RefactoringActionRule *Rule : MatchingRules) {
+            if (!Rule->hasSelectionRequirement())
+              continue;
+            TestRefactoringResultConsumer Consumer;
+            Rule->invoke(Consumer, Context);
+            return std::move(*Consumer.Result);
+          }
+          llvm_unreachable("The action must have at least one selection rule");
+        });
+  }
+
+  bool invokeAction(RefactoringActionSubcommand &Subcommand) {
+    const RefactoringAction &Action = Subcommand.getAction();
+    const ActionState &ActionInfo = State[&Action];
+
+    // Find a set of matching rules.
+    SmallVector<RefactoringActionRule *, 4> MatchingRules;
+    llvm::StringSet<> MissingOptions;
+
+    bool HasSelection = false;
+    for (const auto &Rule : ActionInfo.Rules) {
+      if (Rule->hasSelectionRequirement()) {
+        HasSelection = true;
+        if (!Subcommand.getSelection().empty())
+          MatchingRules.push_back(Rule.get());
+        else
+          MissingOptions.insert("selection");
+      }
+      // FIXME (Alex L): Support custom options.
+    }
+    if (MatchingRules.empty()) {
+      llvm::errs() << "error: '" << Subcommand.getName()
+                   << "' can't be invoked with the given arguments:\n";
+      for (const auto &Opt : MissingOptions)
+        llvm::errs() << "  missing '-" << Opt.getKey() << "' option\n";
+      return true;
+    }
+
+    bool HasFailed = false;
+    if (foreachTranslationUnit(Subcommand, [&](ASTContext &AST) {
+          RefactoringRuleContext Context(AST.getSourceManager());
+          Context.setASTContext(AST);
+
+          if (HasSelection && Subcommand.getTestSelection()) {
+            // Use a slightly different invocation path for tests.
+            HasFailed = runSelectionTestInvocations(
+                Subcommand, Context, *Subcommand.getTestSelection(),
+                MatchingRules);
+            return;
+          }
+          // FIXME (Alex L): Implement non-test invocation path.
+          // FIXME (Alex L): If more than one initiation succeeded, then the
+          // rules are ambiguous.
+        }))
+      return true;
+    return HasFailed;
+  }
+};
+
+} // end anonymous namespace
+
+int main(int argc, const char **argv) {
+  ToolRefactoringEngine Engine;
+  Engine.initialize();
+
+  cl::HideUnrelatedOptions(opts::CommonRefactorOptions);
+  cl::ParseCommandLineOptions(
+      argc, argv, "Clang-based refactoring tool for C, C++ and Objective-C");
+  cl::PrintOptionValues();
+
+  // Figure out which action is given by the user.
+  auto It = llvm::find_if(
+      Engine.SubCommands,
+      [](const std::unique_ptr<RefactoringActionSubcommand> &SubCommand) {
+        return !!(*SubCommand);
+      });
+  if (It == Engine.SubCommands.end()) {
+    llvm::errs() << "error: no refactoring action given\n";
+    llvm::errs() << "note: the following actions are supported:\n";
+    for (const auto &Subcommand : Engine.SubCommands)
+      llvm::errs().indent(2) << Subcommand->getName() << "\n";
+    return 1;
+  }
+  RefactoringActionSubcommand &ActionCommand = **It;
+
+  ArrayRef<std::string> Sources = ActionCommand.getSources();
+  // When -no-dbs is used, at least one file (TU) must be given to any
+  // subcommand.
+  if (opts::NoDatabases && Sources.empty()) {
+    llvm::errs() << "error: must provide paths to the source files when "
+                    "'-no-dbs' is used\n";
+    return 1;
+  }
+  if (Engine.invokeAction(ActionCommand))
+    return 1;
+
+  return 0;
+}

tools/clang-refactor/DumpRefactoringResult.cpp

+//===--- TestSupport.cpp - Clang-based refactoring tool -------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief This file implements routines that provide refactoring testing
+/// utilities.
+///
+//===----------------------------------------------------------------------===//
+
+#include "RefactoringResult.h"
+#include "clang/Basic/SourceManager.h"
+#include "clang/Tooling/Refactoring/RefactoringResultConsumer.h"
+
+using namespace llvm;
+using namespace clang;
+using namespace tooling;
+
+void clang_refactor::internal::dump(const SymbolOccurrence &Occurrence,
+                                    raw_ostream &OS, const SourceManager &SM,
+                                    int Indent) {
+  OS.indent(Indent);
+  switch (Occurrence.getKind()) {
+  case SymbolOccurrence::MatchingSymbol:
+    OS << "symbol ";
+    break;
+  }
+  for (const auto &I : llvm::enumerate(Occurrence.getNameRanges())) {
+    if (I.index())
+      OS << ", ";
+    SourceRange Range = I.value();
+    auto DumpLoc = [&](SourceLocation L) {
+      std::pair<FileID, unsigned> LocInfo = SM.getDecomposedLoc(L);
+      if (LocInfo.first.isInvalid()) {
+        OS << "<invalid>";
+        return;
+      }
+      OS << SM.getLineNumber(LocInfo.first, LocInfo.second) << ':'
+         << SM.getColumnNumber(LocInfo.first, LocInfo.second);
+    };
+    DumpLoc(Range.getBegin());
+    OS << " -> ";
+    DumpLoc(Range.getEnd());
+    OS << "\n";
+  }
+}

tools/clang-refactor/RefactoringResult.h

+//===--- RefactoringResult.h - Clang-based refactoring tool -----*- 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_TOOLS_CLANG_REFACTOR_REFACTORING_RESULT_H
+#define LLVM_CLANG_TOOLS_CLANG_REFACTOR_REFACTORING_RESULT_H
+
+#include "clang/Basic/LLVM.h"
+#include "clang/Tooling/Refactoring/RefactoringResultConsumer.h"
+#include "llvm/Support/raw_ostream.h"
+#include <vector>
+
+namespace clang {
+
+class SourceManager;
+
+namespace clang_refactor {
+
+/// An abstract interface that defines common useful operations that can be
+/// performed on any refactoring result.
+class AbstractRefactoringResult {
+public:
+  virtual ~AbstractRefactoringResult() {}
+
+  virtual int getTypeId() const = 0;
+
+  virtual bool operator==(const AbstractRefactoringResult &Other) const = 0;
+  bool operator!=(const AbstractRefactoringResult &Other) const {
+    return !(*this == Other);
+  }
+
+  /// Refactoring results can be dumped by clang-refactor using the -dump
+  /// option.
+  virtual void dump(llvm::raw_ostream &OS, const SourceManager &SM,
+                    int Indent = 0) const = 0;
+};
+
+namespace internal {
+
+template <typename T> struct RefactoringResultTypeId {};
+template <> struct RefactoringResultTypeId<tooling::AtomicChanges> {
+  static constexpr int value = 0;
+};
+template <> struct RefactoringResultTypeId<tooling::SymbolOccurrences> {
+  static constexpr int value = 1;
+};
+
+template <typename T> bool isEqualTo(const T &LHS, const T &RHS) {
+  return LHS == RHS;
+}
+
+template <typename T>
+bool isEqualTo(const std::vector<T> &LHS, const std::vector<T> &RHS) {
+  for (const auto &I : llvm::zip(LHS, RHS)) {
+    if (!(std::get<0>(I) == std::get<1>(I)))
+      return false;
+  }
+  return true;
+}
+
+void dump(const tooling::SymbolOccurrence &Occurrences, llvm::raw_ostream &OS,
+          const SourceManager &SM, int Indent);
+
+template <typename T>
+void dump(const std::vector<T> &Values, llvm::raw_ostream &OS,
+          const SourceManager &SM, int Indent) {
+  for (const auto &I : Values)
+    dump(I, OS, SM, Indent);
+}
+
+} // end namespace internal
+
+/// Implements \c AbstractRefactoringResult for the specific refactoring result
+/// type.
+template <typename T>
+class RefactoringResultWrapper : public AbstractRefactoringResult {
+public:
+  RefactoringResultWrapper(T Value) : Value(std::move(Value)) {}
+
+  int getTypeId() const override {
+    return internal::RefactoringResultTypeId<T>::value;
+  }
+
+  bool operator==(const AbstractRefactoringResult &Other) const override {
+    if (getTypeId() != Other.getTypeId())
+      return false;
+    return internal::isEqualTo(
+        Value, static_cast<const RefactoringResultWrapper<T> &>(Other).Value);
+  }
+
+  void dump(llvm::raw_ostream &OS, const SourceManager &SM,
+            int Indent) const override {
+    internal::dump(Value, OS, SM, Indent);
+  }
+
+  T Value;
+};
+
+} // end namespace clang_refactor
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLS_CLANG_REFACTOR_REFACTORING_RESULT_H

tools/clang-refactor/TestSupport.h

+//===--- TestSupport.h - Clang-based refactoring tool -----------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Declares datatypes and routines that are used by test-specific code
+/// in clang-refactor.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_CLANG_REFACTOR_TEST_SUPPORT_H
+#define LLVM_CLANG_TOOLS_CLANG_REFACTOR_TEST_SUPPORT_H
+
+#include "RefactoringResult.h"
+#include "clang/Basic/LLVM.h"
+#include "clang/Basic/SourceLocation.h"
+#include "llvm/ADT/Optional.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/Support/Error.h"
+#include <map>
+#include <string>
+
+namespace clang {
+
+class SourceManager;
+
+namespace clang_refactor {
+
+/// A source selection range that's specified in a test file using an inline
+/// command in the comment. These commands can take the following forms:
+///
+/// - /*range=*/ will create an empty selection range in the default group
+///   right after the comment.
+/// - /*range a=*/ will create an empty selection range in the 'a' group right
+///   after the comment.
+/// - /*range = +1*/ will create an empty selection range at a location that's
+///   right after the comment with one offset to the column.
+/// - /*range= -> +2:3*/ will create a selection range that starts at the
+///   location right after the comment, and ends at column 3 of the 2nd line
+///   after the line of the starting location.
+///
+/// Clang-refactor will expected all ranges in one test group to produce
+/// identical results.
+struct TestSelectionRange {
+  unsigned Begin, End;
+};
+
+/// A set of test selection ranges specified in one file.
+struct TestSelectionRangesInFile {
+  std::string Filename;
+  std::map<std::string, SmallVector<TestSelectionRange, 8>> GroupedRanges;
+
+  TestSelectionRangesInFile(TestSelectionRangesInFile &&) = default;
+  TestSelectionRangesInFile &operator=(TestSelectionRangesInFile &&) = default;
+
+  bool dispatch(
+      const SourceManager &SM,
+      llvm::function_ref<
+          Expected<std::unique_ptr<AbstractRefactoringResult>>(SourceRange)>
+          Producer) const;
+
+  void dump(llvm::raw_ostream &OS) const;
+};
+
+/// Extracts the grouped selection ranges from the file that's specified in
+/// the -selection=test:<filename> option.
+///
+/// The grouped ranges are specified in comments using the following syntax:
+/// "range" [ group-name ] "=" [ "+" starting-column-offset ] [ "->"
+///                              "+" ending-line-offset ":"
+///                                  ending-column-position ]
+///
+/// The selection range is then computed from this command by taking the ending
+/// location of the comment, and adding 'starting-column-offset' to the column
+/// for that location. That location in turns becomes the whole selection range,
+/// unless 'ending-line-offset' and 'ending-column-position' are specified. If
+/// they are specified, then the ending location of the selection range is
+/// the starting location's line + 'ending-line-offset' and the
+/// 'ending-column-position' column.
+///
+/// All selection ranges in one group are expected to produce the same
+/// refactoring result.
+///
+/// When testing, zero is returned from clang-refactor even when a group
+/// produces an initiation error, which is different from normal invocation
+/// that returns a non-zero value. This is done on purpose, to ensure that group
+/// consistency checks can return non-zero, but still dump the output of
+/// the group. So even if a test matches the output of group, it will still fail
+/// because clang-refactor should return zero on exit when the group results are
+/// consistent.
+///
+/// \returns None on failure (errors are emitted to stderr), or a set of
+/// grouped source ranges in the given file otherwise.
+Optional<TestSelectionRangesInFile>
+findTestSelectionRangesIn(StringRef Filename);
+
+} // end namespace clang_refactor
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLS_CLANG_REFACTOR_TEST_SUPPORT_H

tools/clang-refactor/TestSupport.cpp

+//===--- TestSupport.cpp - Clang-based refactoring tool -------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief This file implements routines that provide refactoring testing
+/// utilities.
+///
+//===----------------------------------------------------------------------===//
+
+#include "TestSupport.h"
+#include "clang/Basic/SourceManager.h"
+#include "clang/Lex/Lexer.h"
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/ErrorOr.h"
+#include "llvm/Support/Regex.h"
+#include "llvm/Support/raw_ostream.h"
+
+using namespace llvm;
+using namespace clang;
+using namespace clang_refactor;
+
+void TestSelectionRangesInFile::dump(raw_ostream &OS) const {
+  for (const auto &Group : GroupedRanges) {
+    OS << "Test selection group '" << Group.first << "':\n";
+    for (const auto &Range : Group.second) {
+      OS << "  " << Range.Begin << "-" << Range.End << "\n";
+    }
+  }
+}
+
+bool TestSelectionRangesInFile::dispatch(
+    const SourceManager &SM,
+    llvm::function_ref<
+        Expected<std::unique_ptr<AbstractRefactoringResult>>(SourceRange)>
+        Producer) const {
+  const FileEntry *FE = SM.getFileManager().getFile(Filename);
+  FileID FID = FE ? SM.translateFile(FE) : FileID();
+  if (!FE || FID.isInvalid()) {
+    llvm::errs() << "error: -selection=test:" << Filename
+                 << " : given file is not in the target TU";
+    return true;
+  }
+  SourceLocation FileLoc = SM.getLocForStartOfFile(FID);
+  bool Failed = false;
+  for (const auto &Group : GroupedRanges) {
+    // All ranges in the group must produce the same result.
+    std::unique_ptr<AbstractRefactoringResult> CanonicalResult;
+    Optional<std::string> CanonicalErrorMessage;
+    for (const TestSelectionRange &Range : Group.second) {
+      // Translate the offset pair to a true source range.
+      SourceLocation Start =
+          SM.getMacroArgExpandedLocation(FileLoc.getLocWithOffset(Range.Begin));
+      SourceLocation End =
+          SM.getMacroArgExpandedLocation(FileLoc.getLocWithOffset(Range.End));
+      assert(Start.isValid() && End.isValid() && "unexpected invalid range");
+
+      Expected<std::unique_ptr<AbstractRefactoringResult>> Result =
+          Producer(SourceRange(Start, End));
+      std::string ErrorMessage;
+      bool HasResult = !!Result;
+      if (!HasResult) {
+        // FIXME: Handle diagnostic error as well.
+        handleAllErrors(Result.takeError(), [&](StringError &Err) {
+          ErrorMessage = Err.getMessage();
+        });
+      }
+      if (!CanonicalResult && !CanonicalErrorMessage) {
+        if (HasResult)
+          CanonicalResult = std::move(*Result);
+        else
+          CanonicalErrorMessage = std::move(ErrorMessage);
+        continue;
+      }
+
+      // Verify that this result corresponds to the canonical result.
+      if (CanonicalErrorMessage) {
+        // The error messages must match.
+        if (!HasResult && ErrorMessage == *CanonicalErrorMessage)
+          continue;
+      } else {
+        assert(CanonicalResult && "missing canonical result");
+        // The results must match.
+        if (HasResult && **Result == *CanonicalResult)
+          continue;
+      }
+      Failed = true;
+      // Report the mismatch.
+      llvm::errs()
+          << "error: unexpected refactoring result for range starting at "
+          << SM.getLineNumber(FID, Range.Begin) << ':'
+          << SM.getColumnNumber(FID, Range.Begin) << " in group '"
+          << Group.first << "':\n  ";
+      if (HasResult)
+        llvm::errs() << "valid result";
+      else
+        llvm::errs() << "error '" << ErrorMessage << "'";
+      llvm::errs() << " does not match initial ";
+      if (CanonicalErrorMessage)
+        llvm::errs() << "error '" << *CanonicalErrorMessage << "'\n";
+      else
+        llvm::errs() << "valid result\n";
+      if (HasResult && !CanonicalErrorMessage) {
+        llvm::errs() << "  Expected to Produce:\n";
+        CanonicalResult->dump(llvm::errs(), SM, /*Indent=*/4);
+        llvm::errs() << "  Produced:\n";
+        (*Result)->dump(llvm::errs(), SM, /*Indent=*/4);
+      }
+    }
+
+    // Dump the results:
+    if (!CanonicalResult) {
+      llvm::errs() << Group.second.size() << " '" << Group.first
+                   << "' results:\n";
+      llvm::errs() << *CanonicalErrorMessage << "\n";
+    } else {
+      llvm::outs() << Group.second.size() << " '" << Group.first
+                   << "' results:\n";
+      CanonicalResult->dump(llvm::outs(), SM);
+    }
+  }
+  return Failed;
+}
+
+/// Adds the \p ColumnOffset to file offset \p Offset, without going past a
+/// newline.
+static unsigned addColumnOffset(StringRef Source, unsigned Offset,
+                                unsigned ColumnOffset) {
+  if (!ColumnOffset)
+    return Offset;
+  StringRef Substr = Source.drop_front(Offset).take_front(ColumnOffset);
+  size_t NewlinePos = Substr.find_first_of("\r\n");
+  return Offset +
+         (NewlinePos == StringRef::npos ? ColumnOffset : (unsigned)NewlinePos);
+}
+
+Optional<TestSelectionRangesInFile>
+clang_refactor::findTestSelectionRangesIn(StringRef Filename) {
+  ErrorOr<std::unique_ptr<MemoryBuffer>> ErrOrFile =
+      MemoryBuffer::getFile(Filename);
+  if (!ErrOrFile) {
+    llvm::errs() << "error: -selection=test:" << Filename
+                 << " : could not open the given file";
+    return None;
+  }
+  StringRef Source = ErrOrFile.get()->getBuffer();
+
+  // FIXME (Alex L): 3rd capture groups for +line:column.
+  // See the doc comment for this function for the explanation of this
+  // syntax.
+  static Regex RangeRegex("range[[:blank:]]*([[:alpha:]_]*)?[[:blank:]]*=[[:"
+                          "blank:]]*(\\+[[:digit:]]+)?");
+
+  TestSelectionRangesInFile TestRanges = {Filename.str(), {}};
+
+  LangOptions LangOpts;
+  LangOpts.CPlusPlus = 1;
+  LangOpts.CPlusPlus11 = 1;
+  Lexer Lex(SourceLocation::getFromRawEncoding(0), LangOpts, Source.begin(),
+            Source.begin(), Source.end());
+  Lex.SetCommentRetentionState(true);
+  Token Tok;
+  for (Lex.LexFromRawLexer(Tok); Tok.isNot(tok::eof);
+       Lex.LexFromRawLexer(Tok)) {
+    if (Tok.isNot(tok::comment))
+      continue;
+    StringRef Comment =
+        Source.substr(Tok.getLocation().getRawEncoding(), Tok.getLength());
+    SmallVector<StringRef, 4> Matches;
+    if (!RangeRegex.match(Comment, &Matches)) {
+      // Try to detect mistyped 'range:' comments to ensure tests don't miss
+      // anything.
+      if (Comment.contains_lower("range") && !Comment.contains_lower("run")) {
+        llvm::errs() << "error: suspicious comment '" << Comment
+                     << "' that "
+                        "resembles the range command found\n";
+        llvm::errs() << "note: please reword if this isn't a range command\n";
+        return None;
+      }
+      continue;
+    }
+    unsigned Offset = Tok.getEndLoc().getRawEncoding();
+    unsigned ColumnOffset = 0;
+    if (!Matches[2].empty()) {
+      // Don't forget to drop the '+'!
+      if (Matches[2].drop_front().getAsInteger(10, ColumnOffset))
+        assert(false && "regex should have produced a number");
+    }
+    // FIXME (Alex L): Support true ranges.
+    Offset = addColumnOffset(Source, Offset, ColumnOffset);
+    TestSelectionRange Range = {Offset, Offset};
+    auto It = TestRanges.GroupedRanges.insert(std::make_pair(
+        Matches[1].str(), SmallVector<TestSelectionRange, 8>{Range}));
+    if (!It.second)
+      It.first->second.push_back(Range);
+  }
+  if (TestRanges.GroupedRanges.empty()) {
+    llvm::errs() << "error: -selection=test:" << Filename
+                 << ": no 'range' commands";
+    return None;
+  }
+  return std::move(TestRanges);
+}