From d889bc4bafdb40b228e07d4594fb5902cd7d0a62 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Sat, 10 Oct 2026 20:10:22 -0700 Subject: [PATCH 1/3] Resolve documentation links for private Hex dependencies The docs task now reads the project lock and recognizes organization repositories in seven- and eight-element Hex lock entries. For those dependencies, it builds URLs using the organization host, locked package name, and loaded application version. Other entries retain the existing URL format, and explicit dependency URL overrides still take precedence. The added regression test covers private direct and transitive dependencies, overrides, applications without version metadata, and fallback handling. Fixes #1975 --- lib/mix/tasks/docs.ex | 20 ++++++++- test/mix/tasks/docs_test.exs | 86 ++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 0431dbb36..fc427f298 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -298,13 +298,31 @@ defmodule Mix.Tasks.Docs do end defp get_deps do + lock = Mix.Dep.Lock.read() + for {key, _} <- Mix.Project.deps_paths(), _ = Application.load(key), vsn = Application.spec(key, :vsn) do - {key, "https://#{String.replace("#{key}", "_", "-")}.hexdocs.pm/#{vsn}/"} + {key, dependency_url(key, vsn, lock[key])} end end + defp dependency_url(app, vsn, lock) + when is_tuple(lock) and tuple_size(lock) in [7, 8] and elem(lock, 0) == :hex do + case {elem(lock, 1), elem(lock, 6)} do + {package, "hexpm:" <> organization} + when (is_atom(package) or is_binary(package)) and organization != "" -> + "https://#{organization}.hexdocs.pm/#{package}/#{vsn}/" + + _ -> + dependency_url(app, vsn, nil) + end + end + + defp dependency_url(app, vsn, _lock) do + "https://#{String.replace("#{app}", "_", "-")}.hexdocs.pm/#{vsn}/" + end + defp put_package(options, config) do if package = config[:package] do Keyword.put(options, :package, package[:name] || config[:app]) diff --git a/test/mix/tasks/docs_test.exs b/test/mix/tasks/docs_test.exs index 1d32728d2..89a177209 100644 --- a/test/mix/tasks/docs_test.exs +++ b/test/mix/tasks/docs_test.exs @@ -177,6 +177,92 @@ defmodule Mix.Tasks.DocsTest do {:earmark_parser, "foo"} end + test "includes private dependency URLs from the project lock", %{tmp_dir: tmp_dir} = context do + deps_path = Mix.Project.deps_path() + + File.write!(Path.join(tmp_dir, "mix.exs"), """ + defmodule PrivateDocsProject do + use Mix.Project + + def project do + [ + app: :private_docs, + version: "0.1.0", + deps_path: #{inspect(deps_path)}, + deps: [ + {:earmark_parser, path: #{inspect(Path.join(deps_path, "earmark_parser"))}}, + {:makeup_elixir, path: #{inspect(Path.join(deps_path, "makeup_elixir"))}}, + {:missing_docs_app, path: #{inspect(Path.join(deps_path, "earmark_parser"))}, app: false} + ] + ] + end + end + """) + + lock = %{ + earmark_parser: + {:hex, :private_parser, "0.0.1", "checksum", [:mix], [], "hexpm:my-org", "checksum"}, + makeup: {:hex, :"private-makeup", "0.0.1", "checksum", [:mix], [], "hexpm:my-org"} + } + + File.write!(Path.join(tmp_dir, "mix.lock"), inspect(lock)) + project = Mix.Project.pop() + + try do + Mix.Project.in_project(:private_docs, tmp_dir, fn _ -> + try do + assert [{_, _, _, options}] = run(context, [], app: :private_docs) + + assert options[:deps][:earmark_parser] == + "https://my-org.hexdocs.pm/private_parser/#{Application.spec(:earmark_parser, :vsn)}/" + + assert options[:deps][:makeup] == + "https://my-org.hexdocs.pm/private-makeup/#{Application.spec(:makeup, :vsn)}/" + + refute Keyword.has_key?(options[:deps], :missing_docs_app) + + assert [{_, _, _, options}] = + run(context, [], + app: :private_docs, + docs: [deps: [earmark_parser: "foo", missing_docs_app: "bar"]] + ) + + assert options[:deps][:earmark_parser] == "foo" + refute Keyword.has_key?(options[:deps], :missing_docs_app) + + for entry <- [ + nil, + {:git, "https://example.com/repo.git", "ref", []}, + {:hex, :private_parser, "0.0.1"}, + Tuple.insert_at(lock.earmark_parser, 8, :unknown), + put_elem(lock.earmark_parser, 6, "hexpm"), + put_elem(lock.earmark_parser, 6, "custom-repo"), + put_elem(lock.earmark_parser, 6, nil), + put_elem(lock.earmark_parser, 6, "hexpm:") + ] do + lock = + if entry, + do: %{lock | earmark_parser: entry}, + else: Map.delete(lock, :earmark_parser) + + File.write!("mix.lock", inspect(lock)) + + assert [{_, _, _, options}] = run(context, [], app: :private_docs) + + assert options[:deps][:earmark_parser] == + "https://earmark-parser.hexdocs.pm/#{Application.spec(:earmark_parser, :vsn)}/" + end + after + Mix.Project.clear_deps_cache() + end + end) + after + :code.purge(PrivateDocsProject) + :code.delete(PrivateDocsProject) + Mix.Project.push(project.name, project.file) + end + end + test "accepts lazy docs", context do assert [ {"ex_doc", "dev", _, From 2f3ff366616230d8d1c6c901510040ea24c20ddb Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Tue, 13 Oct 2026 23:41:58 -0700 Subject: [PATCH 2/3] Use hexorgs.pm for private dependency docs and test through run Private organization dependencies now link to https://.hexorgs.pm///, as suggested in review. The private lock test now calls run/3 against the current project with a temporary lockfile, like the other tests in the file, instead of building a throwaway Mix project. --- lib/mix/tasks/docs.ex | 2 +- test/mix/tasks/docs_test.exs | 119 ++++++++++++++--------------------- 2 files changed, 47 insertions(+), 74 deletions(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index fc427f298..02f951d02 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -312,7 +312,7 @@ defmodule Mix.Tasks.Docs do case {elem(lock, 1), elem(lock, 6)} do {package, "hexpm:" <> organization} when (is_atom(package) or is_binary(package)) and organization != "" -> - "https://#{organization}.hexdocs.pm/#{package}/#{vsn}/" + "https://#{organization}.hexorgs.pm/#{package}/#{vsn}/" _ -> dependency_url(app, vsn, nil) diff --git a/test/mix/tasks/docs_test.exs b/test/mix/tasks/docs_test.exs index 89a177209..1d189437d 100644 --- a/test/mix/tasks/docs_test.exs +++ b/test/mix/tasks/docs_test.exs @@ -178,88 +178,61 @@ defmodule Mix.Tasks.DocsTest do end test "includes private dependency URLs from the project lock", %{tmp_dir: tmp_dir} = context do - deps_path = Mix.Project.deps_path() - - File.write!(Path.join(tmp_dir, "mix.exs"), """ - defmodule PrivateDocsProject do - use Mix.Project - - def project do - [ - app: :private_docs, - version: "0.1.0", - deps_path: #{inspect(deps_path)}, - deps: [ - {:earmark_parser, path: #{inspect(Path.join(deps_path, "earmark_parser"))}}, - {:makeup_elixir, path: #{inspect(Path.join(deps_path, "makeup_elixir"))}}, - {:missing_docs_app, path: #{inspect(Path.join(deps_path, "earmark_parser"))}, app: false} - ] - ] - end - end - """) - lock = %{ earmark_parser: {:hex, :private_parser, "0.0.1", "checksum", [:mix], [], "hexpm:my-org", "checksum"}, makeup: {:hex, :"private-makeup", "0.0.1", "checksum", [:mix], [], "hexpm:my-org"} } - File.write!(Path.join(tmp_dir, "mix.lock"), inspect(lock)) - project = Mix.Project.pop() + lockfile = Path.join(tmp_dir, "mix.lock") + File.write!(lockfile, inspect(lock)) + previous_lockfile = Mix.Project.config()[:lockfile] + Mix.ProjectStack.merge_config(lockfile: lockfile) try do - Mix.Project.in_project(:private_docs, tmp_dir, fn _ -> - try do - assert [{_, _, _, options}] = run(context, [], app: :private_docs) - - assert options[:deps][:earmark_parser] == - "https://my-org.hexdocs.pm/private_parser/#{Application.spec(:earmark_parser, :vsn)}/" - - assert options[:deps][:makeup] == - "https://my-org.hexdocs.pm/private-makeup/#{Application.spec(:makeup, :vsn)}/" - - refute Keyword.has_key?(options[:deps], :missing_docs_app) - - assert [{_, _, _, options}] = - run(context, [], - app: :private_docs, - docs: [deps: [earmark_parser: "foo", missing_docs_app: "bar"]] - ) - - assert options[:deps][:earmark_parser] == "foo" - refute Keyword.has_key?(options[:deps], :missing_docs_app) - - for entry <- [ - nil, - {:git, "https://example.com/repo.git", "ref", []}, - {:hex, :private_parser, "0.0.1"}, - Tuple.insert_at(lock.earmark_parser, 8, :unknown), - put_elem(lock.earmark_parser, 6, "hexpm"), - put_elem(lock.earmark_parser, 6, "custom-repo"), - put_elem(lock.earmark_parser, 6, nil), - put_elem(lock.earmark_parser, 6, "hexpm:") - ] do - lock = - if entry, - do: %{lock | earmark_parser: entry}, - else: Map.delete(lock, :earmark_parser) - - File.write!("mix.lock", inspect(lock)) - - assert [{_, _, _, options}] = run(context, [], app: :private_docs) - - assert options[:deps][:earmark_parser] == - "https://earmark-parser.hexdocs.pm/#{Application.spec(:earmark_parser, :vsn)}/" - end - after - Mix.Project.clear_deps_cache() - end - end) + assert [{_, _, _, options}] = run(context, [], app: :ex_doc) + + assert options[:deps][:earmark_parser] == + "https://my-org.hexorgs.pm/private_parser/#{Application.spec(:earmark_parser, :vsn)}/" + + assert options[:deps][:makeup] == + "https://my-org.hexorgs.pm/private-makeup/#{Application.spec(:makeup, :vsn)}/" + + refute Keyword.has_key?(options[:deps], :missing_docs_app) + + assert [{_, _, _, options}] = + run(context, [], + app: :ex_doc, + docs: [deps: [earmark_parser: "foo", missing_docs_app: "bar"]] + ) + + assert options[:deps][:earmark_parser] == "foo" + refute Keyword.has_key?(options[:deps], :missing_docs_app) + + for entry <- [ + nil, + {:git, "https://example.com/repo.git", "ref", []}, + {:hex, :private_parser, "0.0.1"}, + Tuple.insert_at(lock.earmark_parser, 8, :unknown), + put_elem(lock.earmark_parser, 6, "hexpm"), + put_elem(lock.earmark_parser, 6, "custom-repo"), + put_elem(lock.earmark_parser, 6, nil), + put_elem(lock.earmark_parser, 6, "hexpm:") + ] do + lock = + if entry, + do: %{lock | earmark_parser: entry}, + else: Map.delete(lock, :earmark_parser) + + File.write!(lockfile, inspect(lock)) + + assert [{_, _, _, options}] = run(context, [], app: :ex_doc) + + assert options[:deps][:earmark_parser] == + "https://earmark-parser.hexdocs.pm/#{Application.spec(:earmark_parser, :vsn)}/" + end after - :code.purge(PrivateDocsProject) - :code.delete(PrivateDocsProject) - Mix.Project.push(project.name, project.file) + Mix.ProjectStack.merge_config(lockfile: previous_lockfile) end end From 5df372b022f0cf4bd870127c5888076051105192 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Thu, 15 Oct 2026 07:56:46 -0700 Subject: [PATCH 3/3] Find private Hex dependencies through Mix.Dep.cached Read private dependency organizations from Mix.Dep.cached, keyed on dep.scm == Hex.SCM and dep.opts[:repo], instead of parsing the lock file. The test now seeds the cached deps rather than a temporary lockfile. --- lib/mix/tasks/docs.ex | 31 ++++++++++--------- test/mix/tasks/docs_test.exs | 60 ++++++++++++++++++++---------------- 2 files changed, 49 insertions(+), 42 deletions(-) diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 02f951d02..e4943b9a4 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -298,28 +298,29 @@ defmodule Mix.Tasks.Docs do end defp get_deps do - lock = Mix.Dep.Lock.read() + private_deps = private_hex_deps() - for {key, _} <- Mix.Project.deps_paths(), - _ = Application.load(key), - vsn = Application.spec(key, :vsn) do - {key, dependency_url(key, vsn, lock[key])} + for {app, _} <- Mix.Project.deps_paths(), + _ = Application.load(app), + vsn = Application.spec(app, :vsn) do + {app, dependency_url(app, vsn, private_deps[app])} end end - defp dependency_url(app, vsn, lock) - when is_tuple(lock) and tuple_size(lock) in [7, 8] and elem(lock, 0) == :hex do - case {elem(lock, 1), elem(lock, 6)} do - {package, "hexpm:" <> organization} - when (is_atom(package) or is_binary(package)) and organization != "" -> - "https://#{organization}.hexorgs.pm/#{package}/#{vsn}/" + defp private_hex_deps do + for %Mix.Dep{app: app, scm: Hex.SCM, opts: opts} <- Mix.Dep.cached(), + package = opts[:hex] || app, + "hexpm:" <> organization <- [opts[:repo]], + organization != "", + into: %{}, + do: {app, {package, organization}} + end - _ -> - dependency_url(app, vsn, nil) - end + defp dependency_url(_app, vsn, {package, organization}) do + "https://#{organization}.hexorgs.pm/#{package}/#{vsn}/" end - defp dependency_url(app, vsn, _lock) do + defp dependency_url(app, vsn, _dep) do "https://#{String.replace("#{app}", "_", "-")}.hexdocs.pm/#{vsn}/" end diff --git a/test/mix/tasks/docs_test.exs b/test/mix/tasks/docs_test.exs index 1d189437d..922a755a1 100644 --- a/test/mix/tasks/docs_test.exs +++ b/test/mix/tasks/docs_test.exs @@ -177,19 +177,29 @@ defmodule Mix.Tasks.DocsTest do {:earmark_parser, "foo"} end - test "includes private dependency URLs from the project lock", %{tmp_dir: tmp_dir} = context do - lock = %{ - earmark_parser: - {:hex, :private_parser, "0.0.1", "checksum", [:mix], [], "hexpm:my-org", "checksum"}, - makeup: {:hex, :"private-makeup", "0.0.1", "checksum", [:mix], [], "hexpm:my-org"} - } - - lockfile = Path.join(tmp_dir, "mix.lock") - File.write!(lockfile, inspect(lock)) - previous_lockfile = Mix.Project.config()[:lockfile] - Mix.ProjectStack.merge_config(lockfile: lockfile) + test "includes private dependency URLs from cached deps", context do + cache_key = {:cached_deps, Mix.Project.get()} + deps = Mix.Dep.cached() + previous = Mix.State.read_cache(cache_key) + + put_deps = fn updates -> + updated = + Enum.map(deps, fn %Mix.Dep{app: app, opts: opts} = dep -> + case updates[app] do + {scm, extra} -> %{dep | scm: scm, opts: Keyword.merge(opts, extra)} + nil -> dep + end + end) + + Mix.State.write_cache(cache_key, {{Mix.env(), Mix.target()}, updated}) + end try do + put_deps.(%{ + earmark_parser: {Hex.SCM, hex: "private_parser", repo: "hexpm:my-org"}, + makeup: {Hex.SCM, hex: "private-makeup", repo: "hexpm:my-org"} + }) + assert [{_, _, _, options}] = run(context, [], app: :ex_doc) assert options[:deps][:earmark_parser] == @@ -209,22 +219,14 @@ defmodule Mix.Tasks.DocsTest do assert options[:deps][:earmark_parser] == "foo" refute Keyword.has_key?(options[:deps], :missing_docs_app) - for entry <- [ - nil, - {:git, "https://example.com/repo.git", "ref", []}, - {:hex, :private_parser, "0.0.1"}, - Tuple.insert_at(lock.earmark_parser, 8, :unknown), - put_elem(lock.earmark_parser, 6, "hexpm"), - put_elem(lock.earmark_parser, 6, "custom-repo"), - put_elem(lock.earmark_parser, 6, nil), - put_elem(lock.earmark_parser, 6, "hexpm:") + for update <- [ + {Hex.SCM, hex: "private_parser", repo: "hexpm"}, + {Hex.SCM, hex: "private_parser", repo: "custom-repo"}, + {Hex.SCM, hex: "private_parser", repo: "hexpm:"}, + {Hex.SCM, hex: "private_parser", repo: nil}, + {Mix.SCM.Git, hex: "private_parser", repo: "hexpm:my-org"} ] do - lock = - if entry, - do: %{lock | earmark_parser: entry}, - else: Map.delete(lock, :earmark_parser) - - File.write!(lockfile, inspect(lock)) + put_deps.(%{earmark_parser: update}) assert [{_, _, _, options}] = run(context, [], app: :ex_doc) @@ -232,7 +234,11 @@ defmodule Mix.Tasks.DocsTest do "https://earmark-parser.hexdocs.pm/#{Application.spec(:earmark_parser, :vsn)}/" end after - Mix.ProjectStack.merge_config(lockfile: previous_lockfile) + if previous do + Mix.State.write_cache(cache_key, previous) + else + Mix.State.delete_cache(cache_key) + end end end