fix(doc): resolve same-contract references to anchor links (#15672)

* fix(doc): resolve same-contract references to anchor links

References naming a member of the contract being rendered, like
{toEthSignedMessageHash}, degraded to inline code because the global
name index only contains top-level items, and {Contract-member}
self-references were routed through the ambiguous name index even
though the target page is the one being rendered.

Both now resolve lexically to anchor-only links on the current page,
before any global name lookup.

* fix(doc): validate qualified local reference members

---------

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

Author: mattsse

crates/doc/src/hir_ext.rs

@@ -642,6 +642,46 @@ pub(crate) fn clean_block_doc_content(raw: &str) -> String {
 
 // ── inline link replacement ───────────────────────────────────────────────────
 
+/// Members of the contract page currently being rendered.
+///
+/// Used to resolve `{member}` and `{Contract-member}` references lexically:
+/// a name that belongs to the current contract links to its heading anchor on
+/// the same page instead of going through the global name index (which only
+/// contains top-level items and could otherwise resolve to an unrelated page).
+#[derive(Debug)]
+pub struct LocalMembers {
+    /// The current contract's name.
+    name: String,
+    /// Member names with a heading (and thus an anchor) on the current page.
+    members: HashSet<String>,
+}
+
+impl LocalMembers {
+    /// Create an empty member set for the contract `name`.
+    pub fn new(name: &str) -> Self {
+        Self { name: name.to_string(), members: HashSet::new() }
+    }
+
+    /// Record a member that is rendered as a `### member` heading on the page.
+    pub fn insert(&mut self, member: &str) {
+        self.members.insert(member.to_string());
+    }
+
+    /// Anchor for a bare `{member}` reference, if `member` is documented on this page.
+    ///
+    /// Overloads share the base heading slug; the first heading owns it.
+    fn member_anchor(&self, member: &str) -> Option<String> {
+        self.members.contains(member).then(|| slug_anchor_segment(member))
+    }
+
+    /// Anchor for a qualified `{Contract-member[-params...]}` reference, if `member` is
+    /// documented on this page.
+    fn xref_member_anchor(&self, part: &str) -> Option<String> {
+        let member = part.split('-').find(|piece| !piece.is_empty())?;
+        self.members.contains(member).then(|| xref_part_anchor(part))
+    }
+}
+
 /// Escape a string for use as a markdown link label.
 ///
 /// Prevents MDX from treating user-controlled NatSpec label text as JSX or
@@ -654,7 +694,17 @@ fn escape_link_label(s: &str) -> String {
 ///
 /// Matches the legacy pattern: `{[xref-]Ident[-part]}[label]` where `label` defaults
 /// to `Ident`.
-pub fn replace_inline_links(text: &str, name_to_page: &NameToPage, current_page: &Path) -> String {
+///
+/// Resolution prefers lexical proximity: a reference naming a member of the current
+/// contract (`{member}`, or `{Contract-member}` where `Contract` is the current
+/// contract) becomes an anchor-only link within the page; everything else goes
+/// through the global `name_to_page` index.
+pub fn replace_inline_links(
+    text: &str,
+    name_to_page: &NameToPage,
+    current_page: &Path,
+    local: Option<&LocalMembers>,
+) -> String {
     let mut out = String::with_capacity(text.len());
     let bytes = text.as_bytes();
     let mut i = 0;
@@ -671,6 +721,31 @@ pub fn replace_inline_links(text: &str, name_to_page: &NameToPage, current_page:
                     lookup_name
                 };
 
+                // Same-contract references resolve to anchor-only links: a bare
+                // `{member}` documented on this page, or `{Contract-member}` where
+                // `Contract` is the contract being rendered.
+                if let Some(local) = local {
+                    let anchor = match part {
+                        None => local.member_anchor(lookup_name),
+                        Some(member) if lookup_name == local.name => {
+                            local.xref_member_anchor(member)
+                        }
+                        Some(_) => None,
+                    };
+                    if let Some(anchor) = anchor
+                        && !anchor.is_empty()
+                    {
+                        let default_display = match part {
+                            Some(member) => format!("{lookup_name}.{member}"),
+                            None => lookup_name.to_string(),
+                        };
+                        let display = escape_link_label(label.unwrap_or(&default_display));
+                        out.push_str(&format!("[{display}](#{anchor})"));
+                        i += end;
+                        continue;
+                    }
+                }
+
                 if let Some(candidates) = name_to_page.get(lookup_name) {
                     let page = resolve_page(candidates, current_page);
                     let mut link = page_link(page, current_page);
@@ -845,11 +920,85 @@ mod tests {
             "See {xref-ERC721-_safeMint-address-uint256-}.",
             &name_to_page,
             Path::new("src/contract.Child.mdx"),
+            None,
         );
 
         assert_eq!(
             out,
             "See [ERC721._safeMint-address-uint256-](/src/contract.ERC721#_safemint-address-uint256)."
         );
     }
+
+    #[test]
+    fn same_contract_member_links_anchor_only() {
+        let name_to_page = NameToPage::new();
+        let mut local = LocalMembers::new("ECDSA");
+        local.insert("toEthSignedMessageHash");
+        local.insert("tryRecover");
+
+        // Bare member reference -> anchor-only link.
+        let out = replace_inline_links(
+            "then calling {toEthSignedMessageHash} on it.",
+            &name_to_page,
+            Path::new("src/library.ECDSA.mdx"),
+            Some(&local),
+        );
+        assert_eq!(out, "then calling [toEthSignedMessageHash](#toethsignedmessagehash) on it.");
+
+        // `{Contract-member}` self-reference -> anchor-only link.
+        let out = replace_inline_links(
+            "Overload of {ECDSA-tryRecover} that ...",
+            &name_to_page,
+            Path::new("src/library.ECDSA.mdx"),
+            Some(&local),
+        );
+        assert_eq!(out, "Overload of [ECDSA.tryRecover](#tryrecover) that ...");
+
+        // Unknown member still falls back to inline code.
+        let out = replace_inline_links(
+            "See {unknownMember}.",
+            &name_to_page,
+            Path::new("src/library.ECDSA.mdx"),
+            Some(&local),
+        );
+        assert_eq!(out, "See `unknownMember`.");
+
+        // Unknown qualified self-reference should not create a broken same-page anchor.
+        let out = replace_inline_links(
+            "See {ECDSA-doesNotExist}.",
+            &name_to_page,
+            Path::new("src/library.ECDSA.mdx"),
+            Some(&local),
+        );
+        assert_eq!(out, "See `ECDSA`.");
+    }
+
+    #[test]
+    fn local_member_wins_over_global_name() {
+        // A top-level item elsewhere shares the member's name; lexical
+        // proximity resolves to the same-page anchor, not the other page.
+        let mut name_to_page = NameToPage::new();
+        name_to_page
+            .by_name
+            .insert("transfer".to_string(), vec![PathBuf::from("src/other/contract.transfer.mdx")]);
+        let mut local = LocalMembers::new("Token");
+        local.insert("transfer");
+
+        let out = replace_inline_links(
+            "Calls {transfer}.",
+            &name_to_page,
+            Path::new("src/contract.Token.mdx"),
+            Some(&local),
+        );
+        assert_eq!(out, "Calls [transfer](#transfer).");
+
+        // Without local context the global index still resolves.
+        let out = replace_inline_links(
+            "Calls {transfer}.",
+            &name_to_page,
+            Path::new("src/contract.Token.mdx"),
+            None,
+        );
+        assert_eq!(out, "Calls [transfer](/src/other/contract.transfer).");
+    }
 }

crates/doc/src/render.rs

@@ -196,7 +196,29 @@ fn render_contract<'ast, 'gcx>(
     deployments: &[Deployment],
 ) -> String {
     let name = c.name.as_str();
-    let comments = collect_comments(docs, name_to_page, page_path);
+
+    // Index the members rendered as headings on this page so `{member}` and
+    // `{Contract-member}` self-references resolve to anchor-only links.
+    let mut local = hir_ext::LocalMembers::new(name);
+    for member in c.body.iter() {
+        match &member.kind {
+            ItemKind::Variable(v) => {
+                if let Some(n) = v.name {
+                    local.insert(n.as_str());
+                }
+            }
+            ItemKind::Function(f) => local.insert(&function_heading(f)),
+            ItemKind::Event(e) => local.insert(e.name.as_str()),
+            ItemKind::Error(e) => local.insert(e.name.as_str()),
+            ItemKind::Struct(s) => local.insert(s.name.as_str()),
+            ItemKind::Enum(e) => local.insert(e.name.as_str()),
+            ItemKind::Udvt(u) => local.insert(u.name.as_str()),
+            _ => {}
+        }
+    }
+    let local = Some(&local);
+
+    let comments = collect_comments(docs, name_to_page, page_path, local);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&comments).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -251,14 +273,14 @@ fn render_contract<'ast, 'gcx>(
                 let vname = v.name.map(|n| n.as_str().to_string()).unwrap_or_default();
                 writeln!(out, "### {vname}").unwrap();
                 writeln!(out).unwrap();
-                let mut c = collect_comments(docs, name_to_page, page_path);
+                let mut c = collect_comments(docs, name_to_page, page_path, local);
                 // Attempt @inheritdoc resolution for public state variables.
                 let inherited = inheritdoc_base(docs).and_then(|base| {
                     hir_id.and_then(|cid| hir_ext::resolve_inheritdoc_var(gcx, cid, &vname, &base))
                 });
                 if let Some(ref base_doc) = inherited {
                     let sanitize =
-                        |s: &str| hir_ext::replace_inline_links(s, name_to_page, page_path);
+                        |s: &str| hir_ext::replace_inline_links(s, name_to_page, page_path, local);
                     if c.notices.is_empty() {
                         let inherited_notices: Vec<String> =
                             base_doc.notices.iter().map(|s| sanitize(s)).collect();
@@ -357,6 +379,7 @@ fn render_contract<'ast, 'gcx>(
                 ctx,
                 name_to_page,
                 page_path,
+                local,
                 inherited.as_ref(),
             );
         }
@@ -368,7 +391,7 @@ fn render_contract<'ast, 'gcx>(
         for (span, e, docs) in &events {
             writeln!(out, "### {}", e.name.as_str()).unwrap();
             writeln!(out).unwrap();
-            let c = collect_comments(docs, name_to_page, page_path);
+            let c = collect_comments(docs, name_to_page, page_path, local);
             write_comment_block(&mut out, &c);
             write_code_block(&mut out, &ctx.dedented_snippet(*span));
             write_param_table(&mut out, "Parameters", &e.parameters, &c, ctx);
@@ -381,7 +404,7 @@ fn render_contract<'ast, 'gcx>(
         for (span, e, docs) in &errors {
             writeln!(out, "### {}", e.name.as_str()).unwrap();
             writeln!(out).unwrap();
-            let c = collect_comments(docs, name_to_page, page_path);
+            let c = collect_comments(docs, name_to_page, page_path, local);
             write_comment_block(&mut out, &c);
             write_code_block(&mut out, &ctx.dedented_snippet(*span));
             write_param_table(&mut out, "Parameters", &e.parameters, &c, ctx);
@@ -394,7 +417,7 @@ fn render_contract<'ast, 'gcx>(
         for (span, s, docs) in &structs {
             writeln!(out, "### {}", s.name.as_str()).unwrap();
             writeln!(out).unwrap();
-            let c = collect_comments(docs, name_to_page, page_path);
+            let c = collect_comments(docs, name_to_page, page_path, local);
             write_comment_block(&mut out, &c);
             write_code_block(&mut out, &ctx.dedented_snippet(*span));
             write_struct_properties_table(&mut out, s.fields, &c, ctx);
@@ -407,7 +430,7 @@ fn render_contract<'ast, 'gcx>(
         for (span, e, docs) in &enums {
             writeln!(out, "### {}", e.name.as_str()).unwrap();
             writeln!(out).unwrap();
-            let c = collect_comments(docs, name_to_page, page_path);
+            let c = collect_comments(docs, name_to_page, page_path, local);
             write_comment_block(&mut out, &c);
             write_code_block(&mut out, &ctx.dedented_snippet(*span));
             write_enum_variants_table(&mut out, e.variants, &c);
@@ -420,7 +443,7 @@ fn render_contract<'ast, 'gcx>(
         for (span, u, docs) in &udvts {
             writeln!(out, "### {}", u.name.as_str()).unwrap();
             writeln!(out).unwrap();
-            let c = collect_comments(docs, name_to_page, page_path);
+            let c = collect_comments(docs, name_to_page, page_path, local);
             write_comment_block(&mut out, &c);
             write_code_block(&mut out, &format!("{};", ctx.dedented_snippet(*span)));
         }
@@ -440,14 +463,14 @@ fn render_free_functions(
     git_url: Option<&str>,
 ) -> String {
     let title = if name.is_empty() { "function" } else { name };
-    let first_comments = collect_comments(overloads[0].2, name_to_page, page_path);
+    let first_comments = collect_comments(overloads[0].2, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, title, first_notice(&first_comments).as_deref());
     writeln!(out, "# {title}").unwrap();
     writeln!(out).unwrap();
     write_git_source(&mut out, git_url);
     for (span, f, docs) in overloads {
-        render_function_section(&mut out, *span, f, docs, ctx, name_to_page, page_path, None);
+        render_function_section(&mut out, *span, f, docs, ctx, name_to_page, page_path, None, None);
     }
     out
 }
@@ -472,7 +495,7 @@ fn render_constants(
         let name = v.name.map(|n| n.as_str().to_string()).unwrap_or_else(|| "_".to_string());
         writeln!(out, "## {name}").unwrap();
         writeln!(out).unwrap();
-        let c = collect_comments(docs, name_to_page, page_path);
+        let c = collect_comments(docs, name_to_page, page_path, None);
         write_comment_block(&mut out, &c);
         write_code_block(&mut out, &ctx.dedented_snippet(*span));
     }
@@ -491,7 +514,7 @@ fn render_struct<'ast>(
     git_url: Option<&str>,
 ) -> String {
     let name = s.name.as_str();
-    let c = collect_comments(docs, name_to_page, page_path);
+    let c = collect_comments(docs, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&c).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -513,7 +536,7 @@ fn render_enum<'ast>(
     git_url: Option<&str>,
 ) -> String {
     let name = e.name.as_str();
-    let c = collect_comments(docs, name_to_page, page_path);
+    let c = collect_comments(docs, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&c).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -535,7 +558,7 @@ fn render_udvt<'ast>(
     git_url: Option<&str>,
 ) -> String {
     let name = u.name.as_str();
-    let c = collect_comments(docs, name_to_page, page_path);
+    let c = collect_comments(docs, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&c).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -556,7 +579,7 @@ fn render_error<'ast>(
     git_url: Option<&str>,
 ) -> String {
     let name = e.name.as_str();
-    let c = collect_comments(docs, name_to_page, page_path);
+    let c = collect_comments(docs, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&c).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -578,7 +601,7 @@ fn render_event<'ast>(
     git_url: Option<&str>,
 ) -> String {
     let name = e.name.as_str();
-    let c = collect_comments(docs, name_to_page, page_path);
+    let c = collect_comments(docs, name_to_page, page_path, None);
     let mut out = String::new();
     write_frontmatter(&mut out, name, first_notice(&c).as_deref());
     writeln!(out, "# {name}").unwrap();
@@ -600,6 +623,7 @@ fn render_function_section(
     ctx: &Ctx<'_>,
     name_to_page: &NameToPage,
     page_path: &Path,
+    local: Option<&hir_ext::LocalMembers>,
     inherited: Option<&hir_ext::InheritedDoc>,
 ) {
     let heading = function_heading(f);
@@ -609,10 +633,10 @@ fn render_function_section(
     }
     writeln!(out, "### {heading}").unwrap();
     writeln!(out).unwrap();
-    let mut c = collect_comments(docs, name_to_page, page_path);
+    let mut c = collect_comments(docs, name_to_page, page_path, local);
     // Merge inherited natspec for missing tags.
     if let Some(inherited) = inherited {
-        let sanitize = |s: &str| hir_ext::replace_inline_links(s, name_to_page, page_path);
+        let sanitize = |s: &str| hir_ext::replace_inline_links(s, name_to_page, page_path, local);
         let inherited_notices: Vec<String> =
             inherited.notices.iter().map(|s| sanitize(s)).collect();
         let inherited_devs: Vec<String> = inherited.devs.iter().map(|s| sanitize(s)).collect();
@@ -724,6 +748,7 @@ fn collect_comments(
     docs: &DocComments<'_>,
     name_to_page: &NameToPage,
     page_path: &Path,
+    local: Option<&hir_ext::LocalMembers>,
 ) -> CommentData {
     let mut data = CommentData {
         titles: Vec::new(),
@@ -779,7 +804,7 @@ fn collect_comments(
             }
 
             // Apply inline {Ident} -> markdown link replacement.
-            let content = hir_ext::replace_inline_links(trimmed, name_to_page, page_path);
+            let content = hir_ext::replace_inline_links(trimmed, name_to_page, page_path, local);
 
             if is_continuation && !prev_doc_was_blank {
                 let appended = match last_section {