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
21 changes: 21 additions & 0 deletions Sources/CLI/cmd/support/SupportArticlesCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import ArgumentParser

struct SupportArticlesCommand: AsyncParsableCommand, GlobalOptionsProviding {
@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "articles", abstract: "Discover categorized support resources.",
subcommands: [SupportArticlesListCommand.self])
}

struct SupportArticlesListCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "Filter by a source category identifier, such as membership.")
var category: String?

static let configuration = CommandConfiguration(
commandName: "list", abstract: "List support article categories and their resource links.")

var request: SupportRequest { .articles(category: category) }
}
45 changes: 45 additions & 0 deletions Sources/CLI/cmd/support/SupportCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import ArgumentParser

struct SupportCommand: AsyncParsableCommand, GlobalOptionsProviding {
@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "support",
abstract: "Browse Apple support resources and read supported HTML content.",
subcommands: [
SupportArticlesCommand.self, SupportGuidesCommand.self, SupportGlossaryCommand.self,
SupportTermsCommand.self, SupportViewCommand.self,
])
}

protocol SupportExecutableCommand: AsyncParsableCommand, GlobalOptionsProviding {
var output: OutputOptions { get }
var request: SupportRequest { get }
}

extension SupportExecutableCommand {
mutating func run() async throws {
try await run(deps: AppleDocs.dependencies)
}

func run(deps: SupportCommandDependencies) async throws {
deps.telemetry.startCommand(
TelemetryCommandContext(
command: request.commandName, outputJSON: output.json, technology: nil, typeName: nil))
let runner = SupportCommandRunner(
service: deps.supportService, renderer: deps.supportRenderer(output: output))
deps.commandOutputWriter.write(try await runner.run(request))
}
}

struct SupportViewCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "A supported path relative to developer.apple.com, including help/ or support/.")
var path: String

static let configuration = CommandConfiguration(
commandName: "view", abstract: "Read a supported HTML document. PDFs and unknown layouts are not parsed.")

var request: SupportRequest { .article(path: path) }
}
48 changes: 48 additions & 0 deletions Sources/CLI/cmd/support/SupportCommandRunner.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
enum SupportRequest: Sendable {
case articles(category: String?)
case helpCatalog
case contents(name: String)
case glossary(query: String?)
case glossaryEntry(term: String)
case terms(category: String?)
case termsEntry(name: String)
case article(path: String)

var commandName: String {
switch self {
case .articles: return "support.articles.list"
case .helpCatalog: return "support.guides.list"
case .contents: return "support.guides.contents"
case .glossary: return "support.glossary.list"
case .glossaryEntry: return "support.glossary.view"
case .terms: return "support.terms.list"
case .termsEntry: return "support.terms.view"
case .article: return "support.view"
}
}
}

struct SupportCommandRunner: Sendable {
private let service: AppleSupportService
private let renderer: SupportRenderer

init(service: AppleSupportService, renderer: SupportRenderer) {
self.service = service
self.renderer = renderer
}

func run(_ request: SupportRequest) async throws -> String {
let payload: SupportPayload
switch request {
case .articles(let category): payload = .articles(try await service.fetchArticles(category: category))
case .helpCatalog: payload = .help(try await service.fetchHelp())
case .contents(let name): payload = .contents(try await service.fetchGuideContents(named: name))
case .glossary(let query): payload = .glossary(try await service.fetchGlossary(query: query))
case .glossaryEntry(let term): payload = .glossaryEntry(try await service.fetchGlossaryEntry(term: term))
case .terms(let category): payload = .terms(try await service.fetchTerms(category: category))
case .termsEntry(let name): payload = .termsEntry(try await service.fetchTermsEntry(named: name))
case .article(let path): payload = .article(try await service.fetchArticle(path: path))
}
return try renderer.render(payload)
}
}
33 changes: 33 additions & 0 deletions Sources/CLI/cmd/support/SupportGlossaryCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import ArgumentParser

struct SupportGlossaryCommand: AsyncParsableCommand, GlobalOptionsProviding {
@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "glossary", abstract: "Look up terms used in Apple development and distribution.",
subcommands: [SupportGlossaryListCommand.self, SupportGlossaryViewCommand.self])
}

struct SupportGlossaryListCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "Filter term names by a case-insensitive substring, not definition text.")
var query: String?

static let configuration = CommandConfiguration(
commandName: "list", abstract: "List glossary terms and structured definitions.")

var request: SupportRequest { .glossary(query: query) }
}

struct SupportGlossaryViewCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "The exact displayed term, matched case-insensitively.")
var term: String

static let configuration = CommandConfiguration(
commandName: "view", abstract: "Show one glossary definition.")

var request: SupportRequest { .glossaryEntry(term: term) }
}
31 changes: 31 additions & 0 deletions Sources/CLI/cmd/support/SupportGuidesCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import ArgumentParser

struct SupportGuidesCommand: AsyncParsableCommand, GlobalOptionsProviding {
@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "guides", abstract: "Discover help resources and browse supported guide contents.",
subcommands: [SupportGuidesListCommand.self, SupportGuidesContentsCommand.self])
}

struct SupportGuidesListCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions

static let configuration = CommandConfiguration(
commandName: "list", abstract: "List featured help resources, topic groups, and the glossary.")

var request: SupportRequest { .helpCatalog }
}

struct SupportGuidesContentsCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "The guide identifier, such as app-store-connect.")
var name: String

static let configuration = CommandConfiguration(
commandName: "contents", abstract: "Show the embedded table of contents for a supported guide.")

var request: SupportRequest { .contents(name: name) }
}
34 changes: 34 additions & 0 deletions Sources/CLI/cmd/support/SupportTermsCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import ArgumentParser

struct SupportTermsCommand: AsyncParsableCommand, GlobalOptionsProviding {
@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "terms", abstract: "Browse the agreements and guidelines catalog.",
subcommands: [SupportTermsListCommand.self, SupportTermsViewCommand.self])
}

struct SupportTermsListCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "Filter by a source category identifier, such as guidelines.")
var category: String?

static let configuration = CommandConfiguration(
commandName: "list", abstract: "List agreements, guidelines, and their available resources.")

var request: SupportRequest { .terms(category: category) }
}

struct SupportTermsViewCommand: SupportExecutableCommand {
@OptionGroup var global: GlobalOptions
@OptionGroup var output: OutputOptions
@Option(help: "The terms entry identifier returned by the catalog.")
var name: String

static let configuration = CommandConfiguration(
commandName: "view",
abstract: "Show a catalog entry and its translations, not the linked legal document.")

var request: SupportRequest { .termsEntry(name: name) }
}
1 change: 1 addition & 0 deletions Sources/CLI/main/CLI.swift
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ struct CLI: AsyncParsableCommand, GlobalOptionsProviding {
subcommands: [
TypesCommand.self,
TechnologiesCommand.self,
SupportCommand.self,
CacheCommand.self,
AgentCommand.self,
]
Expand Down
4 changes: 4 additions & 0 deletions Sources/CLI/main/Dependencies.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ struct Dependencies: Sendable {
let httpCache: URLCache?
let httpDataTransport: URLSession
let documentationRepository: DefaultAppleDocumentationRepository<DefaultAppleDocumentationClient<URLSession>>
let supportService: DefaultAppleSupportService<DefaultAppleSupportClient<URLSession>>

init(telemetry: DefaultTelemetry) {
self.telemetry = telemetry
Expand All @@ -33,6 +34,9 @@ struct Dependencies: Sendable {
configuration.urlCache = httpCache
}
httpDataTransport = URLSession(configuration: configuration)
supportService = DefaultAppleSupportService(
dependencies: DefaultAppleSupportClient(
logger: Logger(label: "com.techprimate.apple-docs.support.client"), dependencies: httpDataTransport))
documentationRepository = DefaultAppleDocumentationRepository(
logger: Logger(label: "com.techprimate.apple-docs.repository"),
dependencies: DefaultAppleDocumentationClient(
Expand Down
24 changes: 24 additions & 0 deletions Sources/CLI/main/SupportDependencies.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
#if DEBUG
protocol AppleSupportServiceProvider {
associatedtype SupportService: AppleSupportService
var supportService: SupportService { get }
}

protocol SupportRendererProvider {
associatedtype SupportOutputRenderer: SupportRenderer
func supportRenderer(output: OutputOptions) -> SupportOutputRenderer
}

typealias SupportCommandDependencies = any (
AppleSupportServiceProvider & SupportRendererProvider & CommandOutputWriterProvider & TelemetryProvider
)
extension Dependencies: AppleSupportServiceProvider, SupportRendererProvider {}
#else
typealias SupportCommandDependencies = Dependencies
#endif

extension Dependencies {
func supportRenderer(output: OutputOptions) -> DefaultSupportRenderer {
DefaultSupportRenderer(output: output.format, audience: output.audience)
}
}
6 changes: 5 additions & 1 deletion Sources/CLI/renderer/SupportContentEncoding.swift
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import Foundation

extension SupportInline {
private enum CodingKeys: CodingKey { case type, text, content, label, url, alt }
private enum CodingKeys: CodingKey { case type, text, content, label, url, alt, name }

func encode(to encoder: any Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
Expand Down Expand Up @@ -29,6 +29,10 @@ extension SupportInline {
try container.encode("link", forKey: .type)
try container.encode(label, forKey: .label)
try container.encode(url, forKey: .url)
case .anchor(let name, let content):
try container.encode("anchor", forKey: .type)
try container.encode(name, forKey: .name)
try container.encode(content, forKey: .content)
case .lineBreak:
try container.encode("lineBreak", forKey: .type)
}
Expand Down
6 changes: 5 additions & 1 deletion Sources/CLI/renderer/SupportTextRenderer.swift
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,10 @@ struct SupportTextRenderer {
return termsEntry(value, level: 1)
case .article(let value):
return [
heading(value.title, level: 1), value.url.absoluteString, plain(value.context ?? ""),
heading(value.title, level: 1), value.url.absoluteString,
plain(
value.breadcrumbs.isEmpty
? value.context ?? "" : value.breadcrumbs.map(\.title).joined(separator: " > ")),
blocks(value.content),
]
+ (value.related.isEmpty ? [] : [heading("Related", level: 2)] + value.related.map(reference))
Expand Down Expand Up @@ -117,6 +120,7 @@ struct SupportTextRenderer {
return agent
? markdown.link(inline(label), target: .external(url))
: inline(label) + " (" + url.absoluteString + ")"
case .anchor(_, let content): return inline(content)
case .lineBreak: return "\n"
}
}.joined()
Expand Down
7 changes: 7 additions & 0 deletions Sources/CLI/support/SupportContent.swift
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ indirect enum SupportInline: Encodable, Equatable, Sendable {
case superscript([SupportInline])
case link(label: [SupportInline], url: URL)
case image(url: URL, alt: String)
case anchor(name: String, content: [SupportInline])
case lineBreak
}

Expand All @@ -33,10 +34,16 @@ struct SupportTableCell: Encodable, Equatable, Sendable {
let rowSpan: Int
}

struct SupportBreadcrumb: Encodable, Equatable, Sendable {
let title: String
let url: URL?
}

struct SupportArticle: Encodable, Equatable, Sendable {
let url: URL
let title: String
let context: String?
var breadcrumbs: [SupportBreadcrumb] = []
let content: [SupportContentBlock]
let related: [SupportPageLink]
let notices: [SupportContentBlock]
Expand Down
10 changes: 9 additions & 1 deletion Sources/CLI/support/SupportHTMLParser+Content.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ extension SupportHTMLParser {
guard let child = node as? Element, !ignored(child) else { return [] }
let content = try inline(in: child)
switch child.tagName() {
case "a": return [.link(label: content, url: try resolve(child.attr("href")))]
case "a": return try inlineLink(child, content: content)
case "em", "i": return [.emphasis(content)]
case "strong", "b": return [.strong(content)]
case "sup": return [.superscript(content)]
Expand All @@ -24,6 +24,14 @@ extension SupportHTMLParser {
}
}

private func inlineLink(_ element: Element, content: [SupportInline]) throws -> [SupportInline] {
if element.hasAttr("href") {
return [.link(label: content, url: try resolve(element.attr("href")))]
}
let name = try element.hasAttr("id") ? element.attr("id") : element.attr("name")
return name.isEmpty ? content : [.anchor(name: name, content: content)]
}

func blocks(in element: Element) throws -> [SupportContentBlock] {
var result: [SupportContentBlock] = []
var pending: [SupportInline] = []
Expand Down
Loading
Loading