Auto link extras: fail on bad path

Author: ftes

lib/ex_doc.ex

@@ -249,6 +249,11 @@ defmodule ExDoc do
     * `:title` - The title of the extra page. If not provided, the title will be inferred from the extra name.
     * `:url` - The external url to link to from the sidebar.
 
+  Links between extras are resolved against the source extra path, not against the flattened output path.
+  Bare filenames such as `[Intro](intro.md)` still match by filename for compatibility, but links that include
+  directories must point to an existing extra source path after normalization, such as
+  `[Intro](../guides/intro.md)` or `[Intro](/guides/intro.md)`.
+
   ### Customizing search data
 
   It is possible to fully customize the way a given extra is indexed, both in autocomplete and in search.

lib/ex_doc/autolink.ex

@@ -52,7 +52,7 @@ defmodule ExDoc.Autolink do
     :language,
     file: "nofile",
     apps: [],
-    extras: [],
+    extras: %{},
     deps: [],
     ext: ".html",
     current_kfa: nil,
@@ -217,7 +217,7 @@ defmodule ExDoc.Autolink do
     with %{scheme: nil, host: nil, path: path} = uri <- URI.parse(link),
          true <- is_binary(path) and path != "" and not (path =~ ref_regex()),
          true <- Path.extname(path) in @builtin_ext do
-      if file = config.extras[Path.basename(path)] do
+      if file = resolve_extra_path(path, config) do
         append_fragment(file <> config.ext, uri.fragment)
       else
         maybe_warn(config, nil, nil, %{file_path: path, original_text: link})
@@ -228,6 +228,47 @@ defmodule ExDoc.Autolink do
     end
   end
 
+  defp resolve_extra_path(path, config) do
+    has_directory? = path != Path.basename(path)
+
+    exact_match = maybe_resolve_extra_source_path(path, config) |> then(&config.extras[&1])
+
+    cond do
+      exact_match ->
+        exact_match
+
+      has_directory? ->
+        nil
+
+      true ->
+        config.extras[Path.basename(path)]
+    end
+  end
+
+  defp maybe_resolve_extra_source_path(path, config) do
+    cond do
+      String.starts_with?(path, "/") ->
+        normalize_extra_source_path(String.trim_leading(path, "/"), File.cwd!())
+
+      true ->
+        normalize_extra_source_path(path, base_dir_for_extra_resolution(config.file))
+    end
+  end
+
+  defp normalize_extra_source_path(path, base_dir) do
+    path
+    |> Path.expand(base_dir)
+    |> Path.relative_to(File.cwd!())
+  end
+
+  defp base_dir_for_extra_resolution(file) when is_binary(file) do
+    file
+    |> Path.expand(File.cwd!())
+    |> Path.dirname()
+  end
+
+  defp base_dir_for_extra_resolution(_), do: File.cwd!()
+
   defp maybe_remove_link(nil, :custom_link) do
     :remove_link
   end

lib/ex_doc/formatter.ex

@@ -313,11 +313,21 @@ defmodule ExDoc.Formatter do
         acc
 
       %ExDoc.ExtraNode{source_path: source_path, id: id}, acc when is_binary(source_path) ->
-        base = Path.basename(source_path)
-        Map.put(acc, base, id)
+        path = normalize_extra_path(source_path)
+        base = Path.basename(path)
+
+        acc
+        |> Map.put(path, id)
+        |> Map.put(base, id)
 
       _extra, acc ->
         acc
     end)
   end
+
+  defp normalize_extra_path(path) do
+    path
+    |> Path.relative_to(File.cwd!())
+    |> String.replace_leading("./", "")
+  end
 end

test/ex_doc/language/elixir_test.exs

@@ -259,7 +259,9 @@ defmodule ExDoc.Language.ElixirTest do
 
     test "extras" do
       opts = [
+        file: "guides/current.md",
         extras: %{
+          "guide/Foo Bar.md" => "foo-bar",
           "Foo Bar.md" => "foo-bar",
           "Bar Baz.livemd" => "bar-baz",
           "Bar Baz.cheatmd" => "bar-baz"
@@ -286,6 +288,32 @@ defmodule ExDoc.Language.ElixirTest do
       assert autolink_doc("[Foo](#baz)", opts) == ~s|<a href="#baz">Foo</a>|
     end
 
+    test "extras relative paths use the extra source path" do
+      opts = [
+        file: "guides/current.md",
+        extras: %{"guide/Foo Bar.md" => "foo-bar", "Foo Bar.md" => "foo-bar"}
+      ]
+
+      assert autolink_doc("[Foo](../guide/Foo Bar.md)", opts) ==
+               ~s|<a href="foo-bar.html">Foo</a>|
+
+      assert autolink_doc("[Foo](/guide/Foo Bar.md)", opts) ==
+               ~s|<a href="foo-bar.html">Foo</a>|
+    end
+
+    test "extras with bad directories warn instead of silently matching by basename" do
+      opts = [
+        warnings: :send,
+        file: "guides/current.md",
+        extras: %{"guide/Foo Bar.md" => "foo-bar", "Foo Bar.md" => "foo-bar"}
+      ]
+
+      assert warn(fn ->
+               assert autolink_doc("[Foo](/bad_dir/Foo Bar.md)", opts) ==
+                        ~s|<a href="/bad_dir/Foo Bar.md">Foo</a>|
+             end) =~ ~s|documentation references file "/bad_dir/Foo Bar.md" but it does not exist|
+    end
+
     test "special case links" do
       assert autolink_doc("`//2`") ==
                ~s|<a href="https://hexdocs.pm/elixir/Kernel.html#//2"><code class="inline">//2</code></a>|

test/ex_doc/language/erlang_test.exs

@@ -669,6 +669,16 @@ defmodule ExDoc.Language.ErlangTest do
       extras: %{"Foo Bar.md" => "foo-bar", "Bar Baz.livemd" => "bar-baz"}
     ]
 
+    @relative_opts [
+      file: "guides/current.md",
+      extras: %{
+        "guide/Foo Bar.md" => "foo-bar",
+        "guide/Bar Baz.livemd" => "bar-baz",
+        "Foo Bar.md" => "foo-bar",
+        "Bar Baz.livemd" => "bar-baz"
+      }
+    ]
+
     test "extras", c do
       assert autolink_doc("[Foo](Foo Bar.md)", c, @opts) ==
                ~s|<a href="foo-bar.html">Foo</a>|
@@ -690,7 +700,7 @@ defmodule ExDoc.Language.ErlangTest do
     end
 
     test "extras relative", c do
-      assert autolink_doc("[Foo](../guide/Foo Bar.md)", c, @opts) ==
+      assert autolink_doc("[Foo](../guide/Foo Bar.md)", c, @relative_opts) ==
                ~s|<a href="foo-bar.html">Foo</a>|
     end
   end