Read extended module from SymbolGraph.

[dylansturg]

Summary

This is a companion change to the change in the Swift compiler to emit the "extended" module as an additional field in the symbol graph. Reading the base and extended modules from the file name is not feasible for module's with long names. A new compiler option was added in Swift #83782 to allow emitting symbol graph file's without both module names in the file name. The shortened format isn't yet supported by swift-docc though.

This also relies on a corresponding change to swift-docc-symbolkit where GraphCollector.moduleNameFor is updated.

The change here consolidates some moduleNameFor functionality where swift-docc was implementing similar behavior as exists in swift-docc-symbolkit, while already depending on symbolkit so it seems prudent to just share the implementation of moduleNameFor.

#1399

Backwards Compatibility

swift-docc must continue to function with symbolgraph data generated by previous versions of the swift toolchain (before swiftlang/swift#86057). This change to swift-docc delegates computing the module name for grouping symbols from swift-docc to existing functionality inside swift-docc-symbolkit, which is already a dependency of the former. The moduleNameFor implementation in swift-docc-symbolkit today detects the extended module name by extracting it from a ModuleNameA@ModuleNameB style file name.

In the related change, to swift-docc-symbolkit, the functionality that is being used from swift-docc-symbolkit is also updated in a backwards compatible way. GraphCollector.moduleNameFor continues to use the existing implementation if the newly added extended field is not present in the symbolgraph.

Dependencies

• Store the name of the extended module in the SymbolGraph. swift#86057
• Read the extended module's name from the SymbolGraph. swift-docc-symbolkit#107

Testing

Describe how a reviewer can test the functionality of your PR. Provide test content to test with if
applicable.

Steps:

1. Provide setup instructions.
2. Explain in detail how the functionality can be tested.

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

No new tests added because all behavior is expected to be identical and existing tests are passing.

[d-ronnqvist]

If I understand correctly, this requires new symbol graph information (the changes to the Swift compiler and SymbolKit) to identify the extended module (because the current code to do is being deleted).

If that's correct, my understanding is that DocC wouldn't be able to correctly identify the extended module for a symbol graph created by any current version of the Swift compiler, or any symbol graphs from Clang or any other source of symbol graph files.
Completely breaking backwards compatibility and breaking compatibility with other sources of symbol graph files would be a deal breaker for this (assuming that I've understood the consequences correctly).

[dylansturg]

If I understand correctly, this requires new symbol graph information (the changes to the Swift compiler and SymbolKit) to identify the extended module (because the current code to do is being deleted).

If that's correct, my understanding is that DocC wouldn't be able to correctly identify the extended module for a symbol graph created by any current version of the Swift compiler, or any symbol graphs from Clang or any other source of symbol graph files. Completely breaking backwards compatibility and breaking compatibility with other sources of symbol graph files would be a deal breaker for this (assuming that I've understood the consequences correctly).

I agree that backwards compatibility important, and breaking swift-docc for the current compiler version would be untenable. But I don't think this change, nor any of the companion changes, breaks backwards compatibility.

The change to swift-docc is aimed at reducing duplication, since both swift-docc and swift-docc-symbolkit have a version of moduleNameFor (for a symbol graph) that does the same thing and is used for similar purposes. So in this PR, I'm suggesting we centralize on 1 implementation of that in swift-docc-symbolkit.

For the companion changes, in swift-docc-symbolkit, I'm proposing a change that is also backwards compatible. When the extended field is set, which requires a new compiler version, GraphCollector.moduleNameFor uses that field. But it also retains the existing implementation to be used when extended is not set. The behavior is unchanged for all existing symbol graph data, and I ran the existing tests in swift-docc-symbolkit to verify that. I still need to add some new tests for the updated symbol graph format of course.

As far as I can tell, each of these changes in isolation and all changes together maintain backwards compatibility. Could you elaborate any on why you believe this is not backwards compatible? Thanks!

[dylansturg]

If I understand correctly, this requires new symbol graph information (the changes to the Swift compiler and SymbolKit) to identify the extended module (because the current code to do is being deleted).

It is true that this PR is deleting code for moduleNameFor in swift-docc, but it's delegating the calls to swift-docc-symbolkit. There is an implementation of moduleNameFor in symbolkit today, which appears to be virtually identical to the implementation here in swift-docc.