Fix links for external dependencies

GearsDatapacks · GearsDatapacks · commit 11ed8c8d96a7 · 2025-05-04T17:27:28.000+01:00
diff --git a/compiler-cli/src/docs.rs b/compiler-cli/src/docs.rs
@@ -1,4 +1,7 @@
-use std::time::{Instant, SystemTime};
+use std::{
+    collections::HashMap,
+    time::{Instant, SystemTime},
+};
 
 use camino::{Utf8Path, Utf8PathBuf};
 use ecow::EcoString;
@@ -9,10 +12,11 @@ use gleam_core::{
     analyse::TargetSupport,
     build::{Codegen, Compile, Mode, Options, Package, Target},
     config::{DocsPage, PackageConfig},
-    docs::DocContext,
+    docs::{Dependency, DependencyKind, DocContext},
     error::Error,
     hex,
     io::HttpClient as _,
+    manifest::ManifestPackageSource,
     paths::ProjectPaths,
     type_,
 };
@@ -49,6 +53,26 @@ pub fn build(paths: &ProjectPaths, options: BuildOptions) -> Result<()> {
     crate::fs::delete_directory(&paths.build_directory_for_target(Mode::Prod, config.target))?;
 
     let out = paths.build_documentation_directory(&config.name);
+
+    let manifest = crate::build::download_dependencies(paths, cli::Reporter::new())?;
+    let dependencies = manifest
+        .packages
+        .iter()
+        .map(|package| {
+            (
+                package.name.clone(),
+                Dependency {
+                    version: package.version.clone(),
+                    kind: match &package.source {
+                        ManifestPackageSource::Hex { .. } => DependencyKind::Hex,
+                        ManifestPackageSource::Git { .. } => DependencyKind::Git,
+                        ManifestPackageSource::Local { .. } => DependencyKind::Path,
+                    },
+                },
+            )
+        })
+        .collect();
+
     let mut built = crate::build::main(
         paths,
         Options {
@@ -60,11 +84,12 @@ pub fn build(paths: &ProjectPaths, options: BuildOptions) -> Result<()> {
             root_target_support: TargetSupport::Enforced,
             no_print_progress: false,
         },
-        crate::build::download_dependencies(paths, cli::Reporter::new())?,
+        manifest,
     )?;
     let outputs = build_documentation(
         paths,
         &config,
+        dependencies,
         &mut built.root_package,
         DocContext::Build,
         &built.module_interfaces,
@@ -106,6 +131,7 @@ fn open_docs(path: &Utf8Path) -> Result<()> {
 pub(crate) fn build_documentation(
     paths: &ProjectPaths,
     config: &PackageConfig,
+    dependencies: HashMap<EcoString, Dependency>,
     compiled: &mut Package,
     is_hex_publish: DocContext,
     cached_modules: &im::HashMap<EcoString, type_::ModuleInterface>,
@@ -121,6 +147,7 @@ pub(crate) fn build_documentation(
     let mut outputs = gleam_core::docs::generate_html(
         paths,
         config,
+        dependencies,
         compiled.modules.as_slice(),
         &pages,
         ProjectIO::new(),
@@ -147,6 +174,25 @@ pub fn publish(paths: &ProjectPaths) -> Result<()> {
     // Reset the build directory so we know the state of the project
     crate::fs::delete_directory(&paths.build_directory_for_target(Mode::Prod, config.target))?;
 
+    let manifest = crate::build::download_dependencies(paths, cli::Reporter::new())?;
+    let dependencies = manifest
+        .packages
+        .iter()
+        .map(|package| {
+            (
+                package.name.clone(),
+                Dependency {
+                    version: package.version.clone(),
+                    kind: match &package.source {
+                        ManifestPackageSource::Hex { .. } => DependencyKind::Hex,
+                        ManifestPackageSource::Git { .. } => DependencyKind::Git,
+                        ManifestPackageSource::Local { .. } => DependencyKind::Path,
+                    },
+                },
+            )
+        })
+        .collect();
+
     let mut built = crate::build::main(
         paths,
         Options {
@@ -158,11 +204,12 @@ pub fn publish(paths: &ProjectPaths) -> Result<()> {
             target: None,
             no_print_progress: false,
         },
-        crate::build::download_dependencies(paths, cli::Reporter::new())?,
+        manifest,
     )?;
     let outputs = build_documentation(
         paths,
         &config,
+        dependencies,
         &mut built.root_package,
         DocContext::HexPublish,
         &built.module_interfaces,
diff --git a/compiler-cli/src/publish.rs b/compiler-cli/src/publish.rs
@@ -6,17 +6,18 @@ use gleam_core::{
     analyse::TargetSupport,
     build::{Codegen, Compile, Mode, Options, Package, Target},
     config::{GleamVersion, PackageConfig, SpdxLicense},
-    docs::DocContext,
+    docs::{Dependency, DependencyKind, DocContext},
     error::{SmallVersion, wrap},
     hex,
+    manifest::ManifestPackageSource,
     paths::{self, ProjectPaths},
     requirement::Requirement,
     type_,
 };
 use hexpm::version::{Range, Version};
 use itertools::Itertools;
 use sha2::Digest;
-use std::{io::Write, path::PathBuf, time::Instant};
+use std::{collections::HashMap, io::Write, path::PathBuf, time::Instant};
 
 use crate::{build, cli, docs, fs, http::HttpClient};
 
@@ -38,6 +39,7 @@ pub fn command(paths: &ProjectPaths, replace: bool, i_am_sure: bool) -> Result<(
         data: package_tarball,
         src_files_added,
         generated_files_added,
+        dependencies,
     } = do_build_hex_tarball(paths, &mut config)?;
 
     check_for_name_squatting(&compile_result)?;
@@ -47,6 +49,7 @@ pub fn command(paths: &ProjectPaths, replace: bool, i_am_sure: bool) -> Result<(
     let docs_tarball = fs::create_tar_archive(docs::build_documentation(
         paths,
         &config,
+        dependencies,
         &mut compile_result,
         DocContext::HexPublish,
         &cached_modules,
@@ -271,6 +274,7 @@ struct Tarball {
     data: Vec<u8>,
     src_files_added: Vec<Utf8PathBuf>,
     generated_files_added: Vec<(Utf8PathBuf, String)>,
+    dependencies: HashMap<EcoString, Dependency>,
 }
 
 pub fn build_hex_tarball(paths: &ProjectPaths, config: &mut PackageConfig) -> Result<Vec<u8>> {
@@ -285,6 +289,25 @@ fn do_build_hex_tarball(paths: &ProjectPaths, config: &mut PackageConfig) -> Res
     // Reset the build directory so we know the state of the project
     fs::delete_directory(&paths.build_directory_for_target(Mode::Prod, target))?;
 
+    let manifest = build::download_dependencies(paths, cli::Reporter::new())?;
+    let dependencies = manifest
+        .packages
+        .iter()
+        .map(|package| {
+            (
+                package.name.clone(),
+                Dependency {
+                    version: package.version.clone(),
+                    kind: match &package.source {
+                        ManifestPackageSource::Hex { .. } => DependencyKind::Hex,
+                        ManifestPackageSource::Git { .. } => DependencyKind::Git,
+                        ManifestPackageSource::Local { .. } => DependencyKind::Path,
+                    },
+                },
+            )
+        })
+        .collect();
+
     // Build the project to check that it is valid
     let built = build::main(
         paths,
@@ -297,7 +320,7 @@ fn do_build_hex_tarball(paths: &ProjectPaths, config: &mut PackageConfig) -> Res
             compile: Compile::All,
             no_print_progress: false,
         },
-        build::download_dependencies(paths, cli::Reporter::new())?,
+        manifest,
     )?;
 
     let minimum_required_version = built.minimum_required_version();
@@ -399,6 +422,7 @@ fn do_build_hex_tarball(paths: &ProjectPaths, config: &mut PackageConfig) -> Res
         data: tarball,
         src_files_added: src_files,
         generated_files_added: generated_files,
+        dependencies,
     })
 }
 
diff --git a/compiler-core/src/docs.rs b/compiler-core/src/docs.rs
@@ -3,9 +3,10 @@ mod source_links;
 #[cfg(test)]
 mod tests;
 
-use std::time::SystemTime;
+use std::{collections::HashMap, time::SystemTime};
 
 use camino::Utf8PathBuf;
+use hexpm::version::Version;
 use printer::Printer;
 
 use crate::{
@@ -36,9 +37,25 @@ pub struct PackageInformation {
     package_config: PackageConfig,
 }
 
+/// Like `ManifestPackage`, but lighter and cheaper to clone as it is all that
+/// we need for printing documentation.
+#[derive(Debug, Clone)]
+pub struct Dependency {
+    pub version: Version,
+    pub kind: DependencyKind,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum DependencyKind {
+    Hex,
+    Path,
+    Git,
+}
+
 pub fn generate_html<IO: FileSystemReader>(
     paths: &ProjectPaths,
     config: &PackageConfig,
+    dependencies: HashMap<EcoString, Dependency>,
     analysed: &[Module],
     docs_pages: &[DocsPage],
     fs: IO,
@@ -174,6 +191,7 @@ pub fn generate_html<IO: FileSystemReader>(
             module.ast.type_info.package.clone(),
             module.name.clone(),
             &module.ast.names,
+            &dependencies,
         );
 
         let types: Vec<TypeDefinition<'_>> = module
diff --git a/compiler-core/src/docs/printer.rs b/compiler-core/src/docs/printer.rs
@@ -20,8 +20,8 @@ use crate::{
 };
 
 use super::{
-    DocsValues, TypeConstructor, TypeConstructorArg, TypeDefinition, markdown_documentation,
-    source_links::SourceLinker, text_documentation,
+    Dependency, DependencyKind, DocsValues, TypeConstructor, TypeConstructorArg, TypeDefinition,
+    markdown_documentation, source_links::SourceLinker, text_documentation,
 };
 
 #[derive(Clone, Copy)]
@@ -55,10 +55,17 @@ pub struct Printer<'a> {
     /// An incrementing number used to generate the next type variable name.
     /// `0` becomes `a`, `1` becomes `b`, etc.
     next_type_variable_id: u64,
+
+    dependencies: &'a HashMap<EcoString, Dependency>,
 }
 
 impl Printer<'_> {
-    pub fn new(package: EcoString, module: EcoString, names: &Names) -> Printer<'_> {
+    pub fn new<'a>(
+        package: EcoString,
+        module: EcoString,
+        names: &'a Names,
+        dependencies: &'a HashMap<EcoString, Dependency>,
+    ) -> Printer<'a> {
         Printer {
             options: PrintOptions::all(),
             names,
@@ -67,6 +74,7 @@ impl Printer<'_> {
             printed_type_variables: HashMap::new(),
             printed_type_variable_names: HashSet::new(),
             next_type_variable_id: 0,
+            dependencies,
         }
     }
 
@@ -521,11 +529,19 @@ impl Printer<'_> {
             ];
             let title = eco_format!("{module}.{{type {name}}}");
 
-            self.link(
-                eco_format!("https://hexdocs.pm/{package}/{module}.html#{name}"),
-                qualified_name,
-                Some(title),
-            )
+            // We can't reliably link to documentation if the type is from a path
+            // or git dependency
+            match self.dependencies.get(package) {
+                Some(Dependency {
+                    kind: DependencyKind::Hex,
+                    version,
+                }) => self.link(
+                    eco_format!("https://hexdocs.pm/{package}/{version}/{module}.html#{name}"),
+                    qualified_name,
+                    Some(title),
+                ),
+                Some(_) | None => self.span_with_title(qualified_name, title),
+            }
         }
     }
 
@@ -626,6 +642,17 @@ impl Printer<'_> {
             zero_width_string("</a>".into()),
         )
     }
+
+    fn span_with_title<'a>(&self, name: impl Documentable<'a>, title: EcoString) -> Document<'a> {
+        if !self.options.print_links {
+            return name.to_doc();
+        }
+
+        name.to_doc().surround(
+            zero_width_string(eco_format!(r#"<span title="{title}">"#)),
+            zero_width_string("</span>".into()),
+        )
+    }
 }
 
 const MAX_COLUMNS: isize = 65;
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_package.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_package.snap
@@ -16,4 +16,4 @@ pub fn make_dict() -> dict.Dict(a, b) { todo }
 ---- VALUES
 
 --- make_dict
-<pre><code>pub fn make_dict() -> <a href="https://hexdocs.pm/gleam_stdlib/gleam/dict.html#Dict" title="gleam/dict.{type Dict}">dict.Dict</a>(a, b)</code></pre>
+<pre><code>pub fn make_dict() -> <a href="https://hexdocs.pm/gleam_stdlib/1.0.0/gleam/dict.html#Dict" title="gleam/dict.{type Dict}">dict.Dict</a>(a, b)</code></pre>
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__no_link_to_type_in_git_dependency.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__no_link_to_type_in_git_dependency.snap
@@ -0,0 +1,19 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- gleam/dict.gleam
+pub type Dict(a, b)
+
+-- main.gleam
+
+import gleam/dict
+
+pub fn make_dict() -> dict.Dict(a, b) { todo }
+
+
+---- VALUES
+
+--- make_dict
+<pre><code>pub fn make_dict() -> <span title="gleam/dict.{type Dict}">dict.Dict</span>(a, b)</code></pre>
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__no_link_to_type_in_path_dependency.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__no_link_to_type_in_path_dependency.snap
@@ -0,0 +1,19 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- gleam/dict.gleam
+pub type Dict(a, b)
+
+-- main.gleam
+
+import gleam/dict
+
+pub fn make_dict() -> dict.Dict(a, b) { todo }
+
+
+---- VALUES
+
+--- make_dict
+<pre><code>pub fn make_dict() -> <span title="gleam/dict.{type Dict}">dict.Dict</span>(a, b)</code></pre>
diff --git a/compiler-core/src/docs/tests.rs b/compiler-core/src/docs/tests.rs
