Fix false positive warning when linking to asset files (#2225)

`build_extra_link` treats `.txt` (amongst other extensions) as a builtin extension
and looks for it in the extras map. Asset files aren't extras, so linking to them
from an extra page produces a false "does not exist" warning.

After failing to match an extra, ExDoc now checks whether the path
corresponds to an existing file in a configured asset directory
before warning.

Closes #2221

Author: eksperimental

lib/ex_doc/autolink.ex

@@ -62,6 +62,7 @@ defmodule ExDoc.Autolink do
     skip_code_autolink_to: &ExDoc.Formatter.Config.skip_code_autolink_to/1,
     force_module_prefix: nil,
     filtered_modules: [],
+    assets: %{},
     warnings: :emit
   ]
 
@@ -217,17 +218,35 @@ 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
-        append_fragment(file <> config.ext, uri.fragment)
-      else
-        maybe_warn(config, nil, nil, %{file_path: path, original_text: link})
-        nil
+      cond do
+        file = config.extras[Path.basename(path)] ->
+          append_fragment(file <> config.ext, uri.fragment)
+
+        asset_file?(path, config.assets) ->
+          nil
+
+        true ->
+          maybe_warn(config, nil, nil, %{file_path: path, original_text: link})
+          nil
       end
     else
       _ -> nil
     end
   end
 
+  defp asset_file?(path, assets) do
+    Enum.any?(assets, fn {source_dir, target_dir} ->
+      prefix = String.trim_trailing(target_dir, "/") <> "/"
+
+      if String.starts_with?(path, prefix) do
+        path
+        |> String.trim_leading(prefix)
+        |> Path.expand(source_dir)
+        |> File.exists?()
+      end
+    end)
+  end
+
   defp maybe_remove_link(nil, :custom_link) do
     :remove_link
   end

lib/ex_doc/formatter.ex

@@ -196,7 +196,8 @@ defmodule ExDoc.Formatter do
       extras: extra_paths(extras),
       skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
       skip_code_autolink_to: config.skip_code_autolink_to,
-      filtered_modules: filtered_nodes
+      filtered_modules: filtered_nodes,
+      assets: config.assets
     }
 
     extras =

test/ex_doc/language/elixir_test.exs

@@ -692,6 +692,57 @@ defmodule ExDoc.Language.ElixirTest do
              ~s|<code class="inline">String.upcase/9</code>|
   end
 
+  @tag :tmp_dir
+  test "asset file warnings", %{tmp_dir: tmp_dir} do
+    lic_dir = Path.join(tmp_dir, "src/licenses")
+    File.mkdir_p!(lic_dir)
+    File.write!(Path.join(lic_dir, "MIT.txt"), "")
+
+    assets_dir = Path.join(tmp_dir, "assets")
+    File.mkdir_p!(Path.join(assets_dir, "sub"))
+    File.write!(Path.join(assets_dir, "sub/file.txt"), "")
+
+    opts = [
+      warnings: :send,
+      extras: %{},
+      assets: %{lic_dir => "LICENSES", assets_dir => "assets"}
+    ]
+
+    # Existing file — no warning
+    refute_warn(fn ->
+      assert autolink_doc("[MIT](LICENSES/MIT.txt)", opts) ==
+               ~s|<a href="LICENSES/MIT.txt">MIT</a>|
+    end)
+
+    # Nested file — no warning
+    refute_warn(fn -> autolink_doc("[License](assets/sub/file.txt)", opts) end)
+
+    # Source and target differ — link must use target dir
+    assert warn(fn -> autolink_doc("[MIT](src/licenses/MIT.txt)", opts) end) =~
+             "but it does not exist"
+
+    # Missing file in asset dir — warns
+    assert warn(fn -> autolink_doc("[License](LICENSES/nonexistent.txt)", opts) end) =~
+             "but it does not exist"
+
+    # Missing nested file — warns
+    assert warn(fn -> autolink_doc("[License](assets/sub/missing.txt)", opts) end) =~
+             "but it does not exist"
+
+    # Path not matching any target dir — warns
+    assert warn(fn -> autolink_doc("[License](other/file.txt)", opts) end) =~
+             "but it does not exist"
+
+    # Target dir prefix must match on "/" boundary
+    assert warn(fn -> autolink_doc("[MIT](LICENSESEXTRA/MIT.txt)", opts) end) =~
+             "but it does not exist"
+
+    # No assets configured — warns
+    assert warn(fn ->
+             autolink_doc("[MIT](LICENSES/MIT.txt)", warnings: :send, extras: %{}, assets: %{})
+           end) =~ "but it does not exist"
+  end
+
   ## Helpers
 
   @default_options [
@@ -718,6 +769,12 @@ defmodule ExDoc.Language.ElixirTest do
     message
   end
 
+  defp refute_warn(fun) when is_function(fun, 0) do
+    fun.()
+
+    refute_received {:warn, _, _}
+  end
+
   defp autolink_spec(spec, options \\ []) do
     config = struct!(ExDoc.Autolink, Keyword.merge(@default_options, options))
     ExDoc.Language.Elixir.autolink_spec(spec, config)