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)#") } ) }