(#1257) Combined module link issue - public extension of dependent module causes resolution failure #1327

mgrebenets · 2025-10-30T07:16:48Z

Bug/issue #, if applicable: #1257

Summary

The basic setup is this:

// ImportedModule
struct ExtendedType {}

struct BaseType {}

// MainModule
import ImportedModule

extension ExtendedType {
    func extensionMethod()
}

With the above we have the following issues:

/ImportedModule/ExtendedType always resolves to the type extension link
/ImportModule/BaseType links are broken
Actually links to any module other than the main one are broken and resolve to plain text like /This/Does/Not/Work

Fix

Prioritize absolute links resolution to point to the module referenced in the link, so that /ImportedModule/BaseType finds the base type because the path starts with /.

To refer to the extended type or method, the non-absolute paths work in Xcode and with docc: ImportedModule/ExtendedType resolves to the type extension page, ImportedModule/ExtendedType/extensionMethod() resolves to the extension method page.

Dependencies

N/A

Testing

‼️🤖 Disclaimer: this is an AI-assisted change.

While AI was utilized to identify and apply the initial fix and create initial version of the tests, the code has been reviewed and modified where needed.

More importantly, I have tested the changes both with the sample project attached to the original issue and with a real work project where I'm using xcodebuild docbuild.

In the real world project I'm dealing with similar setup. ParentFramework imports ChildFramework and extends ChildType and then uses paths like /ChildFramework/ChildType in the documentation.

By passing DOCC_EXEC build setting to xcodebuild docbuild invocation along with --enable-experimental-combined-documentation and other required flags I was able to produce doc archives for the 2 modules, then docc merge them into one and in the resulting doc archive all cross-linking works as expected. I can also ue ChildFramework/ChildType/extensionMethod() links to create reference to the extension method doc page.

Steps for testing with the sample project:

Build the DocC with swift build
Clone the sample attached to original issue: https://github.com/keeshux/docc-combined-link-bug
Go into the cloned sample project and run ./gen-docs.sh
Open .build/plugins/Swift-DocC/outputs/intermediates/SubOne.doccarchive
Check that documentation for ClassOne does not resolve the link and looks like this:

Class one from /Core/Module.

Modify ./gen-docs.sh by adding the following at the start:

export DOCC_EXEC=/path/to/swift-docc/.build/debug/docc

Run ./gen-docs.sh again
Open .build/plugins/Swift-DocC/outputs/intermediates/SubOne.doccarchive again
Confirm that documentation for ClassOne has the /Core/Module link rendered properly

Class one from Module

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

Added tests
Ran the ./bin/test script and it succeeded
Updated documentation if necessary

d-ronnqvist

Thanks for opening this PR and thanks for being upfront about the use of AI assistance.

The new test passes without the changes in PathHierarchy+Find which makes me think that either the test isn't reproducing the issue or possibly that the change isn't doing anything. Can you update the test so that if fails like in #1257 (without the fix and passes with the fix).

d-ronnqvist · 2025-10-31T16:38:05Z

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

    }
-
+
+    func testAbsoluteLinksToOtherModuleWithExtensions() async throws {


This test passes even without the changes in PathHierarchy+Find

mgrebenets · 2025-11-01T04:26:51Z

Thanks for opening this PR and thanks for being upfront about the use of AI assistance.

The new test passes without the changes in PathHierarchy+Find which makes me think that either the test isn't reproducing the issue or possibly that the change isn't doing anything. Can you update the test so that if fails like in #1257 (without the fix and passes with the fix).

Thank you for the feedback and for catching the test behavior!

I dug deeper for better understanding.
The original tests had 2-module setup, while the fix is for 1-module use case.
Basically, the find call for the path from another module is expected to throw an error.
It will be replaced with placeholder like doc://ImportedModule/ExtendedType.
The link points to "nowhere" when single module is built.
Apparently when individual doc archives are merged together (docc merge) the references start pointing at real symbols and become functional. This is what I observed in real world project where I tested the fix.

So the test now makes sure that in-module paths are found and that paths leading to "outside" module can't be found and throw an error, which is expected (to be resolved later when modules are merged).
I also updated the test to enable the experimental linking feature flag at the start.

…endent module causes resolution failure The basic setup is this: ```swift // ImportedModule struct ExtendedType {} struct BaseType {} ``` ```swift // MainModule import ImportedModule extension ExtendedType { func extensionMethod() } ``` With the above we have the following issues: - `/ImportedModule/ExtendedType` **always** resolves to the type extension link - `/ImportModule/BaseType` links are broken Prioritize absolute links resolution to point to the module referenced in the link, so that `/ImportedModule/BaseType` finds the base type because the path starts with `/`. To refer to the extended type or method, the non-absolute paths work in Xcode and with docc: `ImportedModule/ExtendedType` resolves to the type extension page, `ImportedModule/ExtendedType/extensionMethod()` resolves to the extension method page. > ‼️🤖 Disclaimer: this is an AI-assisted change. While AI was utilized to identify and apply the initial fix and create initial version of the tests, the code has been reviewed and modified where needed. More importantly, I have tested the changes both with the sample project attached to the original issue and with a real work project where I'm using `xcodebuild docbuild`. In the real world project I'm dealing with similar setup. `ParentFramework` imports `ChildFramework` and extends `ChildType` and then uses paths like `/ChildFramework/ChildType` in the documentation. By passing `DOCC_EXEC` build setting to `xcodebuild docbuild` invocation along with `--enable-experimental-combined-documentation` and other required flags I was able to produce doc archives for the 2 modules, then `docc merge` them into one and in the resulting doc archive all cross-linking works as expected. I can also ue `ChildFramework/ChildType/extensionMethod()` links to create reference to the extension method doc page.

d-ronnqvist · 2025-11-06T13:12:18Z

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

+            JSONFile(name: "MainModule.symbols.json", content: makeSymbolGraph(
+                moduleName: "MainModule",
+                symbols: [
+                    makeSymbol(id: mainModuleTypeID, kind: .struct, pathComponents: ["MainType"])
+                ]
+            )),


minor: It's unnecessary for the main module symbol graph to define any symbols of its own. The "MainType" symbol is never used in this test so it can be removed to slightly simplify the test setup.

Suggested change

JSONFile(name: "MainModule.symbols.json", content: makeSymbolGraph(

moduleName: "MainModule",

symbols: [

makeSymbol(id: mainModuleTypeID, kind: .struct, pathComponents: ["MainType"])

]

)),

JSONFile(name: "MainModule.symbols.json", content: makeSymbolGraph(moduleName: "MainModule", symbols: [])),

d-ronnqvist · 2025-11-06T13:13:04Z

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

+                    makeSymbol(id: importedProtocolID, kind: .protocol, pathComponents: ["BaseProtocol"]),
+                    makeSymbol(id: importedTypeID, kind: .struct, pathComponents: ["ExtendedType"]),


AFAIK extension symbol graph files (ExtendingName@ExtendedName) don't include the definition of the symbols being extended. Those symbol definitions would belong in the main symbol graph for the ExtendedName module instead.

Suggested change

makeSymbol(id: importedProtocolID, kind: .protocol, pathComponents: ["BaseProtocol"]),

makeSymbol(id: importedTypeID, kind: .struct, pathComponents: ["ExtendedType"]),

d-ronnqvist · 2025-11-06T13:19:59Z

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

+        enableFeatureFlag(\.isExperimentalLinkHierarchySerializationEnabled)
+
+        let importedProtocolID = "s:14ImportedModule12BaseProtocolP"
+        let importedTypeID = "s:14ImportedModule12ExtendedTypeV"


minor: I find that mixing "imported" and "extended" in this test adds unnecessary confusion.

Also, I personally don't find that these string constants help the readability of the test all that much. If they're only used once or twice we could use basic readable inline literals like "extension-id" and "extended-type-id" instead.

d-ronnqvist · 2025-11-06T14:16:28Z

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

+        // Verify that absolute paths to non-existent modules throw moduleNotFound error
+        // This is the fix being tested: without it, single-module fallback would trigger incorrectly


minor: What this comment is describing and what the test assertions below are meant to verify isn't really the same thing.

If we only wanted to verify that non-existent modules result in a moduleNotFound error, then we could use a more explicit path like "/NotFound".

What the test assertions below are meant to verify is that a link that resolves relative to the module fails to resolve as an absolute link, with a moduleNotFound error.

It would be good to both verify that "ExtendedModule/ExtendedType/extensionMethod()" resolves and that "/ExtendedModule/ExtendedType/extensionMethod()" (with a leading slash) raises the expected error.

Also, if it's only these test assertions that are important, then the other test assertions could be removed along with that portion of the code comment.

d-ronnqvist self-requested a review October 31, 2025 15:45

d-ronnqvist requested changes Oct 31, 2025

View reviewed changes

mgrebenets force-pushed the mg/links-fix branch from 1e112bb to bc86b59 Compare November 1, 2025 04:25

mgrebenets force-pushed the mg/links-fix branch from bc86b59 to 4343282 Compare November 1, 2025 04:29

mgrebenets requested a review from d-ronnqvist November 2, 2025 23:53

d-ronnqvist reviewed Nov 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

(#1257) Combined module link issue - public extension of dependent module causes resolution failure #1327

(#1257) Combined module link issue - public extension of dependent module causes resolution failure #1327

Uh oh!

mgrebenets commented Oct 30, 2025 •

edited

Loading

Uh oh!

d-ronnqvist left a comment •

edited

Loading

Uh oh!

d-ronnqvist Oct 31, 2025

Uh oh!

mgrebenets commented Nov 1, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		}


		func testAbsoluteLinksToOtherModuleWithExtensions() async throws {

		makeSymbol(id: importedProtocolID, kind: .protocol, pathComponents: ["BaseProtocol"]),
		makeSymbol(id: importedTypeID, kind: .struct, pathComponents: ["ExtendedType"]),

		// Verify that absolute paths to non-existent modules throw moduleNotFound error
		// This is the fix being tested: without it, single-module fallback would trigger incorrectly

(#1257) Combined module link issue - public extension of dependent module causes resolution failure #1327

Are you sure you want to change the base?

(#1257) Combined module link issue - public extension of dependent module causes resolution failure #1327

Uh oh!

Conversation

mgrebenets commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Fix

Dependencies

Testing

Checklist

Uh oh!

d-ronnqvist left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

mgrebenets commented Nov 1, 2025

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mgrebenets commented Oct 30, 2025 •

edited

Loading

d-ronnqvist left a comment •

edited

Loading