mix xref graph (#4811)

Signed-off-by: José Valim <jose.valim@plataformatec.com.br>

Author: ericentin

lib/mix/lib/mix/tasks/app.tree.ex

@@ -56,7 +56,7 @@ defmodule Mix.Tasks.App.Tree do
 
     if opts[:format] == "dot" do
       Mix.Utils.write_dot_graph!("app_tree.dot", "application tree",
-                                 {:normal, app}, callback, opts)
+                                 [{:normal, app}], callback, opts)
       """
       Generated "app_tree.dot" in the current directory. To generate a PNG:
 
@@ -67,7 +67,7 @@ defmodule Mix.Tasks.App.Tree do
       |> String.trim_trailing
       |> Mix.shell.info
     else
-      Mix.Utils.print_tree({:normal, app}, callback, opts)
+      Mix.Utils.print_tree([{:normal, app}], callback, opts)
     end
   end
 

lib/mix/lib/mix/tasks/deps.tree.ex

@@ -51,7 +51,7 @@ defmodule Mix.Tasks.Deps.Tree do
 
     if opts[:format] == "dot" do
       callback = callback(&format_dot/1, deps, opts)
-      Mix.Utils.write_dot_graph!("deps_tree.dot", "dependency tree", root, callback, opts)
+      Mix.Utils.write_dot_graph!("deps_tree.dot", "dependency tree", [root], callback, opts)
       """
       Generated "deps_tree.dot" in the current directory. To generate a PNG:
 
@@ -63,7 +63,7 @@ defmodule Mix.Tasks.Deps.Tree do
       |> Mix.shell.info
     else
       callback = callback(&format_tree/1, deps, opts)
-      Mix.Utils.print_tree(root, callback, opts)
+      Mix.Utils.print_tree([root], callback, opts)
     end
   end
 

lib/mix/lib/mix/tasks/xref.ex

@@ -2,7 +2,7 @@ defmodule Mix.Tasks.Xref do
   use Mix.Task
 
   alias Mix.Tasks.Compile.Elixir, as: E
-  import Mix.Compilers.Elixir, only: [read_manifest: 2, source: 1, source: 2]
+  import Mix.Compilers.Elixir, only: [read_manifest: 2, source: 1, source: 2, module: 1]
 
   @shortdoc "Performs cross reference checks"
   @recursive true
@@ -12,18 +12,45 @@ defmodule Mix.Tasks.Xref do
 
   ## Xref modes
 
-  The following commands are available:
+  The following commands and options are available:
 
     * `warnings` - prints warnings for violated cross reference checks
+
     * `unreachable` - prints all unreachable "file:line: module.function/arity" entries
+
     * `callers CALLEE` - prints all references of `CALLEE`, which can be one of: `Module`,
       `Module.function`, or `Module.function/arity`
 
-  ## Command line options
+    * `graph` - prints the file reference graph. By default, an edge from `A` to `B` indicates
+      that `A` depends on `B`
+
+      * `--exclude` - paths to exclude
+
+      * `--source` - display only files for which there is a path from the
+        given source file
+
+      * `--sink` - display only files for which there is a path to the
+        given sink file.
+
+      * `--format` - can be set to one of:
+
+        * `pretty` - use Unicode codepoints for formatting the graph. This is the default except on
+          Windows
+
+        * `plain` - do not use Unicode codepoints for formatting the graph. This is the default on
+          Windows
+
+        * `dot` - produces a DOT graph description in `xref_graph.dot` in the
+          current directory. Warning: this will override any previously generated file
+
+  ## Options for all commands
 
     * `--no-compile` - do not compile even if files require compilation
+
     * `--no-deps-check` - do not check dependencies
+
     * `--no-archives-check` - do not check archives
+
     * `--no-elixir-version-check` - do not check the Elixir version from mix.exs
 
   ## Configuration
@@ -36,7 +63,8 @@ defmodule Mix.Tasks.Xref do
   """
 
   @switches [compile: :boolean, deps_check: :boolean, archives_check: :boolean,
-             elixir_version_check: :boolean]
+             elixir_version_check: :boolean, exclude: :keep, format: :string,
+             source: :string, sink: :string]
 
   @doc """
   Runs this task.
@@ -57,8 +85,10 @@ defmodule Mix.Tasks.Xref do
         unreachable()
       ["callers", callee] ->
         callers(callee)
+      ["graph"] ->
+        graph(opts)
       _ ->
-        Mix.raise "xref expects one of the following commands: warnings, unreachable, callers CALLEE"
+        Mix.raise "xref doesn't support this command, see mix help xref for more information"
     end
   end
 
@@ -88,6 +118,12 @@ defmodule Mix.Tasks.Xref do
     :ok
   end
 
+  defp graph(opts) do
+    write_graph(file_references(), excluded(opts), opts)
+
+    :ok
+  end
+
   ## Unreachable
 
   defp unreachable(pair_fun) do
@@ -283,6 +319,124 @@ defmodule Mix.Tasks.Xref do
     Mix.raise message
   end
 
+  ## Graph helpers
+
+  defp excluded(opts) do
+    Keyword.get_values(opts, :exclude)
+    |> Enum.flat_map(&[{&1, nil}, {&1, "(compile)"}, {&1, "(runtime)"}])
+  end
+
+  defp file_references() do
+    module_sources =
+      for manifest <- E.manifests(),
+          manifest_data = read_manifest(manifest, ""),
+          module(module: module, source: source) <- manifest_data,
+          source = Enum.find(manifest_data, &match?(source(source: ^source), &1)),
+          do: {module, source},
+          into: %{}
+
+    all_modules = MapSet.new(module_sources, &elem(&1, 0))
+
+    Map.new module_sources, fn {module, source} ->
+      source(runtime_references: runtime, compile_references: compile, source: file) = source
+      compile_references =
+        compile
+        |> MapSet.new()
+        |> MapSet.delete(module)
+        |> MapSet.intersection(all_modules)
+        |> Enum.filter(&module_sources[&1] != source)
+        |> Enum.map(&{source(module_sources[&1], :source), "(compile)"})
+
+      runtime_references =
+        runtime
+        |> MapSet.new()
+        |> MapSet.delete(module)
+        |> MapSet.intersection(all_modules)
+        |> Enum.filter(&module_sources[&1] != source)
+        |> Enum.map(&{source(module_sources[&1], :source), nil})
+
+      {file, compile_references ++ runtime_references}
+    end
+  end
+
+  defp write_graph(file_references, excluded, opts) do
+    {root, file_references} =
+      case {opts[:source], opts[:sink]} do
+        {nil, nil} ->
+          {Enum.map(file_references, &{elem(&1, 0), nil}) -- excluded, file_references}
+
+        {source, nil} ->
+          if file_references[source] do
+            {[{source, nil}], file_references}
+          else
+            Mix.raise "Source could not be found: #{source}"
+          end
+
+        {nil, sink} ->
+          if file_references[sink] do
+            file_references = filter_for_sink(file_references, sink)
+            roots =
+              file_references
+              |> Map.delete(sink)
+              |> Enum.map(&{elem(&1, 0), nil})
+            {roots -- excluded, file_references}
+          else
+            Mix.raise "Sink could not be found: #{sink}"
+          end
+
+        {_, _} ->
+          Mix.raise "mix xref graph expects only one of --source and --sink"
+      end
+
+    callback =
+      fn {file, type} ->
+        children = Map.get(file_references, file, [])
+        {{file, type}, children -- excluded}
+      end
+
+    if opts[:format] == "dot" do
+      Mix.Utils.write_dot_graph!("xref_graph.dot", "xref graph",
+                                 root, callback, opts)
+      """
+      Generated "xref_graph.dot" in the current directory. To generate a PNG:
+
+         dot -Tpng xref_graph.dot -o xref_graph.png
+
+      For more options see http://www.graphviz.org/.
+      """
+      |> String.trim_trailing()
+      |> Mix.shell.info()
+    else
+      Mix.Utils.print_tree(root, callback, opts)
+    end
+  end
+
+  defp filter_for_sink(file_references, sink) do
+    file_references
+    |> invert_references()
+    |> do_filter_for_sink([{sink, nil}], %{})
+    |> invert_references()
+  end
+
+  defp do_filter_for_sink(file_references, new_nodes, acc) do
+    Enum.reduce new_nodes, acc, fn {new_node_name, _type}, acc ->
+      new_nodes = file_references[new_node_name]
+      if acc[new_node_name] || !new_nodes do
+        acc
+      else
+        do_filter_for_sink(file_references, new_nodes, Map.put(acc, new_node_name, new_nodes))
+      end
+    end
+  end
+
+  defp invert_references(file_references) do
+    Enum.reduce file_references, %{}, fn {file, references}, acc ->
+      Enum.reduce references, acc, fn {reference, type}, acc ->
+        Map.update(acc, reference, [{file, type}], &[{file, type} | &1])
+      end
+    end
+  end
+
   ## Helpers
 
   defp each_source_entries(entries_fun, pair_fun) do

lib/mix/lib/mix/utils.ex

@@ -142,31 +142,40 @@ defmodule Mix.Utils do
     end) |> Enum.uniq
   end
 
+  @type tree_node :: {name :: String.Chars.t, edge_info :: String.Chars.t}
+
   @doc """
   Prints the given tree according to the callback.
 
   The callback will be invoked for each node and it
-  must either return `{printed, children}` tuple or
-  `false` if the given node must not be printed.
+  must return a `{printed, children}` tuple.
   """
-  @spec print_tree(term, (term -> {String.t, [term]}), Keyword.t) :: :ok
-  def print_tree(root, callback, opts \\ []) do
+  @spec print_tree([tree_node], (tree_node -> {tree_node, [tree_node]}), Keyword.t) :: :ok
+  def print_tree(nodes, callback, opts \\ []) do
     pretty =
       case Keyword.get(opts, :format) do
         "pretty" -> true
         "plain" -> false
         _ -> elem(:os.type, 0) != :win32
       end
-    print_tree([root], [], pretty, callback)
+    print_tree(nodes, [], nil, MapSet.new(), pretty, callback)
+
+    :ok
   end
 
-  defp print_tree([], _depth, _pretty, _callback), do: :ok
-  defp print_tree([node | nodes], depth, pretty, callback) do
-    {{name, info}, children} =  callback.(node)
-    space = if info, do: " ", else: ""
-    Mix.shell.info("#{depth(pretty, depth)}#{prefix(pretty, depth, nodes)}#{name}#{space}#{info}")
-    print_tree(children, [(nodes != []) | depth], pretty, callback)
-    print_tree(nodes, depth, pretty, callback)
+  defp print_tree([], _depth, _parent, seen, _pretty, _callback), do: seen
+  defp print_tree([node | nodes], depth, parent, seen, pretty, callback) do
+    {{name, info}, children} = callback.(node)
+    key = {parent, name}
+
+    if MapSet.member?(seen, key) do
+      seen
+    else
+      space = if info, do: " ", else: ""
+      Mix.shell.info("#{depth(pretty, depth)}#{prefix(pretty, depth, nodes)}#{name}#{space}#{info}")
+      seen = print_tree(children, [(nodes != []) | depth], name, MapSet.put(seen, key), pretty, callback)
+      print_tree(nodes, depth, parent, seen, pretty, callback)
+    end
   end
 
   defp depth(_pretty, []),    do: ""
@@ -188,39 +197,44 @@ defmodule Mix.Utils do
   Outputs the given tree according to the callback as a DOT graph.
 
   The callback will be invoked for each node and it
-  must either return `{printed, children}` tuple or
-  `false` if the given node must not be printed.
+  must return a `{printed, children}` tuple.
   """
-  @spec write_dot_graph!(Path.t, String.t, term, (term -> {String.t, [term]}), Keyword.t) :: :ok
-  def write_dot_graph!(path, title, root, callback, _opts \\ []) do
-    {{parent, _}, children} = callback.(root)
-    {dot, _} = build_dot_graph(parent, children, %{}, callback)
+  @spec write_dot_graph!(Path.t, String.t, [tree_node], (tree_node -> {tree_node, [tree_node]}), Keyword.t) :: :ok
+  def write_dot_graph!(path, title, nodes, callback, _opts \\ []) do
+    {dot, _} = build_dot_graph(make_ref(), nodes, MapSet.new(), callback)
     File.write! path, "digraph \"#{title}\" {\n#{dot}}\n"
   end
 
   defp build_dot_graph(_parent, [], seen, _callback), do: {"", seen}
   defp build_dot_graph(parent, [node | nodes], seen, callback) do
     {{name, edge_info}, children} = callback.(node)
-    {current, seen}  = build_dot_current(parent, name, edge_info, seen)
-    {children, seen} = build_dot_graph(name, children, seen, callback)
-    {siblings, seen} = build_dot_graph(parent, nodes, seen, callback)
-    {current <> children <> siblings, seen}
-  end
-
-  defp build_dot_current(parent, name, edge_info, seen) do
     key = {parent, name}
-    case seen do
-      %{^key => _} ->
-        {"", seen}
-      %{} when is_nil(edge_info) ->
-        {~s(  "#{parent}" -> "#{name}"\n),
-         Map.put(seen, key, true)}
-      %{} ->
-        {~s(  "#{parent}" -> "#{name}" [label=\"#{edge_info}\"]\n),
-         Map.put(seen, key, true)}
+
+    if MapSet.member?(seen, key) do
+      {"", seen}
+    else
+      seen = MapSet.put(seen, key)
+      current = build_dot_current(parent, name, edge_info)
+      {children, seen} = build_dot_graph(name, children, seen, callback)
+      {siblings, seen} = build_dot_graph(parent, nodes, seen, callback)
+      {current <> children <> siblings, seen}
     end
   end
 
+  defp build_dot_current(parent, name, edge_info) do
+    edge_info =
+      if edge_info do
+         ~s( [label="#{edge_info}"])
+      end
+
+    parent =
+      unless is_reference(parent) do
+        ~s("#{parent}" -> )
+      end
+
+    ~s(  #{parent}"#{name}"#{edge_info}\n)
+  end
+
   @doc false
   # TODO: Deprecate by 1.4
   def underscore(value) do

lib/mix/test/mix/tasks/app.tree_test.exs

@@ -87,6 +87,7 @@ defmodule Mix.Tasks.App.TreeTest do
 
       assert File.read!("app_tree.dot") == """
         digraph "application tree" {
+          "test"
           "test" -> "elixir"
           "test" -> "logger"
           "logger" -> "elixir"

lib/mix/test/mix/tasks/deps.tree_test.exs

@@ -117,6 +117,7 @@ defmodule Mix.Tasks.Deps.TreeTest do
 
       assert File.read!("deps_tree.dot") == """
         digraph "dependency tree" {
+          "sample"
           "sample" -> "git_repo" [label=">= 0.1.0"]
           "sample" -> "deps_on_git_repo" [label="0.2.0"]
         }
@@ -127,6 +128,7 @@ defmodule Mix.Tasks.Deps.TreeTest do
 
       assert File.read!("deps_tree.dot") == """
         digraph "dependency tree" {
+          "sample"
           "sample" -> "git_repo" [label=">= 0.1.0"]
           "sample" -> "deps_on_git_repo" [label="0.2.0"]
           "deps_on_git_repo" -> "git_repo" [label=""]