[external-links] Display frameworks as beta only if all platforms are beta

[anferbui]

Bug/issue #, if applicable: rdar://128997995

Summary

Symbols can have an availability per platform (iOS, macOS, etc), each of which can be marked as "beta" by providing some metadata when invoking docc:

swift run docc preview preview TestPackage.docc --platform name=macOS,version=40.0.0,beta=true --platform name=iOS,version=50.0.0,beta=true --platform name=watchOS,version=60.0.0,beta=true

A top-level badge is sometimes rendered for a symbol, depending on its platform availability.

Currently there is a mismatch in behaviour where:

• externally resolved links will be shown as beta if any of its available platforms are in beta https://github.com/apple/swift-docc/blob/8f1a9d206ed6cdcf3dccb091fa57216c6d546f21/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L158

  

• internally resolved links will be shown as beta if all of its available platforms are in beta https://github.com/apple/swift-docc/blob/8f1a9d206ed6cdcf3dccb091fa57216c6d546f21/Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift#L208-L240

  

This behaviour is inconsistent and can be confusing for documentation writers. This PR proposes unifying the behaviour so that a symbol is shown as beta if all of its available platforms are in beta.

Implementation

Changes the behaviour of external link resolution in OutOfProcessReferenceResolver to only display a framework to be in beta if all the platforms its supported in are in beta.

This makes it match the behaviour for internal link resolution, so that the behaviour is consistent whether you're linking to a symbol internally within a framework or externally from another framework.

Also modifies LinkDestinationSummary to keep both of the external symbol resolution code paths in sync with each other. Hopefully in the future we can unify and have the same code path for both, but right now the logic is duplicated (and equal).

Dependencies

N/A.

Testing

You can set up a link resolver locally which has beta platform information in order to verify this fix: link-resolver.zip

Excerpt:

"platforms": [
    {
      "name": "macOS",
      "introducedAt": "40.0.0",
      "beta": true
    },
    {
      "introducedAt": "50.0.0",
      "beta": true,
      "name": "iOS"
    },
    {
      "introducedAt": "60.0.0",
      "beta": false,
      "name": "watchOS"
    }
  ]

TestPackage.zip

Steps:

1. Download link-resolver and TestPackage.
2. Render documentation locally:

   DOCC_LINK_RESOLVER_EXECUTABLE=link-resolver swift run docc preview TestPackage.docc --platform name=macOS,version=40.0.0,beta=true --platform name=iOS,version=50.0.0,beta=true

3. Verify that in http://localhost:8080/documentation/testpackage/betaclass, neither of the symbols mentioned have a top level badge that says the symbol is a beta symbol.

Checklist

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

• [x] Added tests
• [x] Ran the ./bin/test script and it succeeded
• [x] [n/a] Updated documentation if necessary

Verification

Unit tests

Added unit tests for OutOfProcessReferenceResolver and ExternalPathHierarchyResolver since these changes affect both types of external link resolution.

Ran ./bin/test:

❯ ./bin/test
Building for debugging...
[122/122] Linking SwiftDocCPackageTests
Build complete! (7.75s)
[1685/1685] Testing SwiftDocCUtilitiesTests.DirectoryMonitorTests/testMonitorDoesNotTriggerUpdates
=> Checking for unacceptable language… okay.
=> Checking license headers… okay.
=> Validating scripts in bin subdirectory… okay.

Site rendering

Before	After

Documentation

As far as I can tell, no changes to the documentation are needed.

[anferbui]

@swift-ci please test

[anferbui]

@swift-ci please test