Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Sources/XCDocsBridge/VectorSearch/VSKAssetObject.swift
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ package struct VSKAssetObject: PrivateObject {
enum Key: String {
case identifier = "stringIdentifier"
case attributes
case payload
}

let base: AnyObject
Expand All @@ -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 [:] }

Expand Down
78 changes: 53 additions & 25 deletions Sources/XCDocsSupport/Search/VectorSearchClient.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
}

Expand All @@ -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(
Expand Down Expand Up @@ -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",
Expand All @@ -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? }
6 changes: 3 additions & 3 deletions Tests/TestSupport/LiveEnvironment.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
51 changes: 35 additions & 16 deletions Tests/XCDocsTests/ClientIntegrationTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)#")
}
)
}
Expand Down
Loading