From 9c54c04ec97c4575083de6c7fb4bf79e86332c4a Mon Sep 17 00:00:00 2001 From: Sam Lazarus Date: Wed, 14 Oct 2026 16:40:16 -0700 Subject: [PATCH] fix: read documentation content from asset payloads Documentation assets built for Xcode 27 leave the `content` attribute empty and store each page's text in its JSON payload. They also split every page into `page#section` entries typed like the page itself, not just topic groups, and keep only the overview on the page. Take `content` from the payload when the attribute is empty, and append every section to its page, not only topics. Look sections up by the pages' framework rather than listing every topic in the asset. Update the live fixtures for the Xcode 27 asset, which renames the Swift Testing framework to Testing and drops the TechnologyOverviews Liquid Glass article. --- .../VectorSearch/VSKAssetObject.swift | 3 + .../Search/VectorSearchClient.swift | 78 +++++++++++++------ Tests/TestSupport/LiveEnvironment.swift | 6 +- .../XCDocsTests/ClientIntegrationTests.swift | 51 ++++++++---- 4 files changed, 94 insertions(+), 44 deletions(-) diff --git a/Sources/XCDocsBridge/VectorSearch/VSKAssetObject.swift b/Sources/XCDocsBridge/VectorSearch/VSKAssetObject.swift index cf3a111..91d5fcc 100644 --- a/Sources/XCDocsBridge/VectorSearch/VSKAssetObject.swift +++ b/Sources/XCDocsBridge/VectorSearch/VSKAssetObject.swift @@ -4,6 +4,7 @@ package struct VSKAssetObject: PrivateObject { enum Key: String { case identifier = "stringIdentifier" case attributes + case payload } let base: AnyObject @@ -12,6 +13,8 @@ package struct VSKAssetObject: PrivateObject { package var identifier: String { value(forKey: .identifier, as: String.self, default: "") } + package var payload: Data? { value(forKey: .payload, as: Data.self) } + package var attributes: [String: String] { guard let attributeDictionary = value(forKey: .attributes, as: NSDictionary.self) else { return [:] } diff --git a/Sources/XCDocsSupport/Search/VectorSearchClient.swift b/Sources/XCDocsSupport/Search/VectorSearchClient.swift index d2e5cb6..ab5ad40 100644 --- a/Sources/XCDocsSupport/Search/VectorSearchClient.swift +++ b/Sources/XCDocsSupport/Search/VectorSearchClient.swift @@ -82,10 +82,14 @@ package final class VectorSearchClient { includeVectors: false, selectedAttributes: selectedAttributes ) - let hit = VectorSearchHit(identifier: await asset.identifier, score: .nan, attributes: await asset.attributes) + let hit = VectorSearchHit( + identifier: await asset.identifier, + score: .nan, + attributes: await attributes(of: asset, includingContent: true) + ) - let descendantsByParent = try await descendantIdentifiersByParent(forParentIdentifiers: [identifier]) - guard descendantsByParent[identifier] != nil else { return hit } + let descendantsByParent = try await descendantIdentifiersByParent(in: [hit]) + guard descendantsByParent[hit.identifier] != nil else { return hit } let expandedHits = try await appendDescendantContents( to: [hit], descendantsByParent: descendantsByParent, @@ -115,9 +119,7 @@ package final class VectorSearchClient { private func hydrateSearchHits(_ hits: [VectorSearchHit], selectedAttributes: [VSKAttributeObject]) async throws -> [VectorSearchHit] { - var attributeNames: [String] = [] - attributeNames.reserveCapacity(selectedAttributes.count) - for attribute in selectedAttributes { attributeNames.append(await attribute.name) } + let attributeNames = await names(of: selectedAttributes) let incompleteIdentifiers = Array( Set( hits.filter { hit in @@ -137,10 +139,11 @@ package final class VectorSearchClient { includeVectors: false, selectedAttributes: selectedAttributes ) + let includesContent = attributeNames.contains("content") var attributesByIdentifier: [String: [String: String]] = [:] for asset in hydratedAssets { let identifier = await asset.identifier - let attributes = await asset.attributes + let attributes = await attributes(of: asset, includingContent: includesContent) attributesByIdentifier[identifier] = attributes.merging(attributesByIdentifier[identifier] ?? [:]) { hydratedValue, existingValue in existingValue.isEmpty ? hydratedValue : existingValue @@ -169,11 +172,12 @@ package final class VectorSearchClient { includeVectors: false, selectedAttributes: selectedAttributes ) + let includesContent = await names(of: selectedAttributes).contains("content") var hitsByIdentifier: [String: VectorSearchHit] = [:] hitsByIdentifier.reserveCapacity(assets.count) for asset in assets { let identifier = await asset.identifier - let attributes = await asset.attributes + let attributes = await attributes(of: asset, includingContent: includesContent) hitsByIdentifier[identifier] = VectorSearchHit(identifier: identifier, score: .nan, attributes: attributes) } @@ -188,37 +192,36 @@ package final class VectorSearchClient { } private func descendantIdentifiersByParent(in hits: [VectorSearchHit]) async throws -> [String: [String]] { - try await descendantIdentifiersByParent( - forParentIdentifiers: hits.map(\.identifier).filter { !$0.contains("#") } - ) - } - - private func descendantIdentifiersByParent(forParentIdentifiers identifiers: [String]) async throws -> [String: - [String]] - { - let parentIdentifiers = orderedUniqueIdentifiers(from: identifiers.filter { !$0.contains("#") }) + let parents = hits.filter { !$0.identifier.contains("#") } + let parentIdentifiers = orderedUniqueIdentifiers(from: parents.map(\.identifier)) guard !parentIdentifiers.isEmpty else { return [:] } - let topicIdentifiers = try await topicIdentifiers() - guard !topicIdentifiers.isEmpty else { return [:] } + // Sections share their page's framework, so a page without one leaves no framework to narrow the lookup by. + let frameworks = parents.contains { ($0.framework ?? "").isEmpty } ? [] : parents.compactMap(\.framework) + let sectionIdentifiers = try await sectionIdentifiers(inFrameworks: Array(Set(frameworks))) + guard !sectionIdentifiers.isEmpty else { return [:] } var descendantsByParent: [String: [String]] = [:] descendantsByParent.reserveCapacity(parentIdentifiers.count) for parentIdentifier in parentIdentifiers { let descendantPrefix = "\(parentIdentifier)#" - let descendants = topicIdentifiers.filter { $0.hasPrefix(descendantPrefix) } + let descendants = sectionIdentifiers.filter { $0.hasPrefix(descendantPrefix) } if !descendants.isEmpty { descendantsByParent[parentIdentifier] = descendants } } return descendantsByParent } - private func topicIdentifiers() async throws -> [String] { - orderedUniqueIdentifiers( - from: try await client.stringIdentifiers( - applying: try await makeFilters(attributeName: "type", values: ["topic"]) - ) + /// Returns the identifiers of the page sections in the given frameworks, or in all frameworks if none are given, + /// in document order. + /// + /// Older documentation assets store only topic groups as separate `page#section` entries. Assets built for + /// Xcode 27 split every page into sections, typed like the page itself, and keep only the overview on the page. + private func sectionIdentifiers(inFrameworks frameworks: [String]) async throws -> [String] { + let identifiers = try await client.stringIdentifiers( + applying: try await makeFilters(attributeName: "framework", values: frameworks) ) + return orderedUniqueIdentifiers(from: identifiers.filter { $0.contains("#") }) } private func appendDescendantContents( @@ -274,6 +277,28 @@ package final class VectorSearchClient { ] } + /// Returns an asset's attributes, taking `content` from the asset's payload when the attribute is empty. + /// + /// Documentation assets built for Xcode 27 leave the `content` attribute empty and store each page's text in a + /// JSON payload instead. + private func attributes(of asset: VSKAssetObject, includingContent includesContent: Bool) async -> [String: String] + { + var attributes = await asset.attributes + guard includesContent, attributes["content"]?.isEmpty ?? true, let payload = await asset.payload, + let content = try? JSONDecoder().decode(DocumentPayload.self, from: payload).content + else { return attributes } + + attributes["content"] = content + return attributes + } + + private func names(of attributes: [VSKAttributeObject]) async -> [String] { + var names: [String] = [] + names.reserveCapacity(attributes.count) + for attribute in attributes { names.append(await attribute.name) } + return names + } + private func missingEntryError(for identifier: String) -> NSError { NSError( domain: "XCDocsSupport.VectorSearchClient", @@ -292,3 +317,6 @@ package final class VectorSearchClient { return uniqueIdentifiers } } + +/// The JSON document a documentation asset stores as its payload. +private struct DocumentPayload: Decodable { let content: String? } diff --git a/Tests/TestSupport/LiveEnvironment.swift b/Tests/TestSupport/LiveEnvironment.swift index 23cf097..6f1a04e 100644 --- a/Tests/TestSupport/LiveEnvironment.swift +++ b/Tests/TestSupport/LiveEnvironment.swift @@ -4,10 +4,10 @@ import XCDocsSupport package enum LiveEnvironment { package static let documentationIdentifier = "/documentation/Testing" - package static let searchFramework = "Swift Testing" + package static let searchFramework = "Testing" package static let searchQuery = "swift testing" - package static let articleWithSubtopicsIdentifier = "/documentation/TechnologyOverviews/liquid-glass" - package static let articleWithSubtopicsQuery = "liquid glass" + package static let articleWithSectionsIdentifier = "/documentation/SwiftUI/Applying-Liquid-Glass-to-custom-views" + package static let articleWithSectionsQuery = "applying liquid glass to custom views" private static let mediaAnalysisServicesPath = "/System/Library/PrivateFrameworks/MediaAnalysisServices.framework" private static let vectorSearchPath = "/System/Library/PrivateFrameworks/VectorSearch.framework" diff --git a/Tests/XCDocsTests/ClientIntegrationTests.swift b/Tests/XCDocsTests/ClientIntegrationTests.swift index ecd3fb1..2f13063 100644 --- a/Tests/XCDocsTests/ClientIntegrationTests.swift +++ b/Tests/XCDocsTests/ClientIntegrationTests.swift @@ -38,15 +38,21 @@ struct ClientIntegrationTests { } @Test - func entryAppendsSubtopicContentForCollectionGroupArticles() async throws { + func entryAppendsSectionContentForSymbols() async throws { guard #available(macOS 26, *) else { return } - try await entryAppendsSubtopicContentForCollectionGroupArticlesOnSupportedOS() + try await entryAppendsSectionContentForSymbolsOnSupportedOS() } @Test - func searchDoesNotReturnArticleSubtopicsSeparatelyWhenParentArticleIsPresent() async throws { + func entryAppendsSectionContentForArticles() async throws { guard #available(macOS 26, *) else { return } - try await searchDoesNotReturnArticleSubtopicsSeparatelyWhenParentArticleIsPresentOnSupportedOS() + try await entryAppendsSectionContentForArticlesOnSupportedOS() + } + + @Test + func searchDoesNotReturnArticleSectionsSeparatelyWhenParentArticleIsPresent() async throws { + guard #available(macOS 26, *) else { return } + try await searchDoesNotReturnArticleSectionsSeparatelyWhenParentArticleIsPresentOnSupportedOS() } @Test @@ -108,29 +114,42 @@ private func entryReturnsExpectedMetadataAndContentOnSupportedOS() async throws } @available(macOS 26, *) -private func entryAppendsSubtopicContentForCollectionGroupArticlesOnSupportedOS() async throws { +private func entryAppendsSectionContentForSymbolsOnSupportedOS() async throws { + let client = Client() + let result = try await client.entry(for: "/documentation/SwiftUI/Color") + let content = try #require(result.content) + + #expect(content.contains("A representation of a color that adapts to a given context.")) + #expect(content.contains("Color: Creating a color")) + #expect(content.contains("Color: Getting standard colors")) +} + +@available(macOS 26, *) +private func entryAppendsSectionContentForArticlesOnSupportedOS() async throws { let client = Client() - let result = try await client.entry(for: LiveEnvironment.articleWithSubtopicsIdentifier) + let result = try await client.entry(for: LiveEnvironment.articleWithSectionsIdentifier) let content = try #require(result.content) - #expect(content.contains("Learn how to design and develop beautiful interfaces that leverage Liquid Glass.")) - #expect(content.contains("Liquid Glass: Introduction to Liquid Glass")) - #expect(content.contains("Liquid Glass: Adopting Liquid Glass")) - #expect(content.contains("Liquid Glass: Essentials")) + #expect(content.contains("Configure, combine, and morph views using Liquid Glass effects.")) + #expect(content.contains("Applying Liquid Glass to custom views: Apply and configure Liquid Glass effects")) + #expect( + content.contains("Applying Liquid Glass to custom views: Combine multiple views with Liquid Glass containers") + ) + #expect(content.contains("Applying Liquid Glass to custom views: Morph Liquid Glass effects during transitions")) } @available(macOS 26, *) -private func searchDoesNotReturnArticleSubtopicsSeparatelyWhenParentArticleIsPresentOnSupportedOS() async throws { +private func searchDoesNotReturnArticleSectionsSeparatelyWhenParentArticleIsPresentOnSupportedOS() async throws { let client = Client() - let results = try await client.search(LiveEnvironment.articleWithSubtopicsQuery, limit: 10, omitContent: false) - let articleResult = try #require(results.first { $0.entry.id == LiveEnvironment.articleWithSubtopicsIdentifier }) + let results = try await client.search(LiveEnvironment.articleWithSectionsQuery, limit: 10, omitContent: false) + let articleResult = try #require(results.first { $0.entry.id == LiveEnvironment.articleWithSectionsIdentifier }) let articleContent = try #require(articleResult.entry.content) - #expect(articleContent.contains("Liquid Glass: Introduction to Liquid Glass")) + #expect(articleContent.contains("Applying Liquid Glass to custom views: Apply and configure Liquid Glass effects")) #expect( results.allSatisfy { result in - result.entry.id == LiveEnvironment.articleWithSubtopicsIdentifier - || !result.entry.id.hasPrefix("\(LiveEnvironment.articleWithSubtopicsIdentifier)#") + result.entry.id == LiveEnvironment.articleWithSectionsIdentifier + || !result.entry.id.hasPrefix("\(LiveEnvironment.articleWithSectionsIdentifier)#") } ) }