From 9c4bc13b21c536772404d02826e3367f84137450 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 13:08:09 +0100 Subject: [PATCH 1/4] feat(support): Render semantic content for humans and agents --- .../CLI/renderer/DefaultSupportRenderer.swift | 25 +++ .../CLI/renderer/SupportContentEncoding.swift | 75 ++++++++ .../CLI/renderer/SupportPresentation.swift | 143 +++++++++++++++ .../CLI/renderer/SupportTextRenderer.swift | 170 ++++++++++++++++++ Sources/CLI/support/SupportCatalogs.swift | 34 ++-- Sources/CLI/support/SupportContent.swift | 10 +- .../renderer/SupportRendererTests.swift | 121 +++++++++++++ 7 files changed, 556 insertions(+), 22 deletions(-) create mode 100644 Sources/CLI/renderer/DefaultSupportRenderer.swift create mode 100644 Sources/CLI/renderer/SupportContentEncoding.swift create mode 100644 Sources/CLI/renderer/SupportPresentation.swift create mode 100644 Sources/CLI/renderer/SupportTextRenderer.swift create mode 100644 Tests/CLITests/renderer/SupportRendererTests.swift diff --git a/Sources/CLI/renderer/DefaultSupportRenderer.swift b/Sources/CLI/renderer/DefaultSupportRenderer.swift new file mode 100644 index 0000000..5fafc29 --- /dev/null +++ b/Sources/CLI/renderer/DefaultSupportRenderer.swift @@ -0,0 +1,25 @@ +import Foundation + +#if DEBUG + protocol SupportRenderer: Sendable { + func render(_ payload: SupportPayload) throws -> String + } + extension DefaultSupportRenderer: SupportRenderer {} +#else + typealias SupportRenderer = DefaultSupportRenderer +#endif + +struct DefaultSupportRenderer: Sendable { + let output: OutputFormat + let audience: OutputAudience + + func render(_ payload: SupportPayload) throws -> String { + let presentation = SupportPresenter().present(payload, audience: audience) + switch output { + case .json: + return try StructuredDocumentationRenderer().render(presentation) + case .text: + return SupportTextRenderer(agent: audience == .agent).render(presentation) + } + } +} diff --git a/Sources/CLI/renderer/SupportContentEncoding.swift b/Sources/CLI/renderer/SupportContentEncoding.swift new file mode 100644 index 0000000..2069a0e --- /dev/null +++ b/Sources/CLI/renderer/SupportContentEncoding.swift @@ -0,0 +1,75 @@ +import Foundation + +extension SupportInline { + private enum CodingKeys: CodingKey { case type, text, content, label, url } + + func encode(to encoder: any Encoder) throws { + var container = encoder.container(keyedBy: CodingKeys.self) + switch self { + case .text(let text): + try container.encode("text", forKey: .type) + try container.encode(text, forKey: .text) + case .code(let text): + try container.encode("code", forKey: .type) + try container.encode(text, forKey: .text) + case .emphasis(let content): + try container.encode("emphasis", forKey: .type) + try container.encode(content, forKey: .content) + case .strong(let content): + try container.encode("strong", forKey: .type) + try container.encode(content, forKey: .content) + case .superscript(let content): + try container.encode("superscript", forKey: .type) + try container.encode(content, forKey: .content) + case .link(let label, let url): + try container.encode("link", forKey: .type) + try container.encode(label, forKey: .label) + try container.encode(url, forKey: .url) + case .lineBreak: + try container.encode("lineBreak", forKey: .type) + } + } +} + +extension SupportContentBlock { + private enum CodingKeys: CodingKey { + case type, content, level, text, anchor, ordered, start, items, syntax, style, rows, url, alt, caption + } + + func encode(to encoder: any Encoder) throws { + var container = encoder.container(keyedBy: CodingKeys.self) + switch self { + case .paragraph(let content): + try container.encode("paragraph", forKey: .type) + try container.encode(content, forKey: .content) + case .heading(let level, let text, let anchor): + try container.encode("heading", forKey: .type) + try container.encode(level, forKey: .level) + try container.encode(text, forKey: .text) + try container.encodeIfPresent(anchor, forKey: .anchor) + case .list(let ordered, let start, let items): + try container.encode("list", forKey: .type) + try container.encode(ordered, forKey: .ordered) + try container.encode(start, forKey: .start) + try container.encode(items, forKey: .items) + case .codeListing(let text, let syntax): + try container.encode("codeListing", forKey: .type) + try container.encode(text, forKey: .text) + try container.encodeIfPresent(syntax, forKey: .syntax) + case .aside(let style, let content): + try container.encode("aside", forKey: .type) + try container.encode(style, forKey: .style) + try container.encode(content, forKey: .content) + case .table(let rows): + try container.encode("table", forKey: .type) + try container.encode(rows, forKey: .rows) + case .image(let url, let alt, let caption): + try container.encode("image", forKey: .type) + try container.encode(url, forKey: .url) + try container.encode(alt, forKey: .alt) + try container.encode(caption, forKey: .caption) + case .separator: + try container.encode("separator", forKey: .type) + } + } +} diff --git a/Sources/CLI/renderer/SupportPresentation.swift b/Sources/CLI/renderer/SupportPresentation.swift new file mode 100644 index 0000000..1abe28c --- /dev/null +++ b/Sources/CLI/renderer/SupportPresentation.swift @@ -0,0 +1,143 @@ +import Foundation + +enum SupportPayload: Sendable { + case articles(SupportArticlesCatalog) + case help(SupportHelpCatalog) + case contents(SupportGuideContents) + case glossary(SupportGlossary) + case glossaryEntry(SupportGlossaryEntry) + case terms(SupportTermsCatalog) + case termsEntry(SupportTermsEntry) + case article(SupportArticle) + + var kind: String { + switch self { + case .articles: return "articlesCatalog" + case .help: return "helpCatalog" + case .contents: return "guideContents" + case .glossary: return "glossary" + case .glossaryEntry: return "glossaryEntry" + case .terms: return "termsCatalog" + case .termsEntry: return "termsEntry" + case .article: return "article" + } + } + + func encodeContent(to encoder: any Encoder) throws { + switch self { + case .articles(let value): try value.encode(to: encoder) + case .help(let value): try value.encode(to: encoder) + case .contents(let value): try value.encode(to: encoder) + case .glossary(let value): try value.encode(to: encoder) + case .glossaryEntry(let value): try value.encode(to: encoder) + case .terms(let value): try value.encode(to: encoder) + case .termsEntry(let value): try value.encode(to: encoder) + case .article(let value): try value.encode(to: encoder) + } + } +} + +struct SupportNavigation: Encodable, Sendable { + let title: String + let url: URL? + let command: String +} + +struct SupportPresentation: Encodable, Sendable { + let payload: SupportPayload + let navigation: [SupportNavigation]? + + private enum CodingKeys: CodingKey { case kind, navigation } + + func encode(to encoder: any Encoder) throws { + try payload.encodeContent(to: encoder) + var container = encoder.container(keyedBy: CodingKeys.self) + try container.encode(payload.kind, forKey: .kind) + try container.encodeIfPresent(navigation, forKey: .navigation) + } +} + +struct SupportPresenter { + func present(_ payload: SupportPayload, audience: OutputAudience) -> SupportPresentation { + SupportPresentation(payload: payload, navigation: audience == .agent ? navigation(payload) : nil) + } + + private func navigation(_ payload: SupportPayload) -> [SupportNavigation] { + switch payload { + case .glossary(let glossary): + return glossary.entries.map { glossaryNavigation($0) } + case .glossaryEntry(let entry): + return [glossaryNavigation(entry)] + case .terms(let catalog): + return catalog.categories.flatMap(\.entries).map(termsNavigation) + case .termsEntry(let entry): + return entry.resources.compactMap { followUp($0.link) } + default: + return references(payload).compactMap(followUp) + } + } + + private func glossaryNavigation(_ entry: SupportGlossaryEntry) -> SupportNavigation { + SupportNavigation( + title: entry.term, url: nil, + command: "apple-docs support glossary view --term " + quote(entry.term) + " --agent") + } + + private func termsNavigation(_ entry: SupportTermsEntry) -> SupportNavigation { + SupportNavigation( + title: entry.title, url: nil, + command: "apple-docs support terms view --name " + quote(entry.id) + " --agent") + } + + private func references(_ payload: SupportPayload) -> [SupportPageLink] { + switch payload { + case .articles(let catalog): return catalog.categories.flatMap(\.links) + case .help(let catalog): + return catalog.featuredResources.map(\.link) + catalog.topics.flatMap { $0.groups.flatMap(\.links) } + + [catalog.glossary.link] + case .contents(let contents): return contents.entries.flatMap(contentsReferences) + case .article(let article): return article.related + default: return [] + } + } + + private func contentsReferences(_ entry: SupportContentsEntry) -> [SupportPageLink] { + (entry.link.map { [$0] } ?? []) + entry.children.flatMap(contentsReferences) + } + + private func followUp(_ link: SupportPageLink) -> SupportNavigation? { + guard let destination = try? SupportDestination(responseURL: link.url) else { return nil } + let path = destination.path + let parts = path.split(separator: "/") + let command: String + switch path { + case "help": command = "apple-docs support guides list" + case "help/glossary": command = "apple-docs support glossary list" + case "support/articles": command = "apple-docs support articles list" + case "support/terms": command = "apple-docs support terms list" + default: + if parts.count == 2, parts[0] == "help", ["account", "app-store-connect", "app-review"].contains(parts[1]) { + command = "apple-docs support guides contents --name " + quote(String(parts[1])) + } else if isReadable(path) { + command = "apple-docs support view --path " + quote(path) + } else { + return nil + } + } + return SupportNavigation(title: link.title, url: link.url, command: command + " --agent") + } + + private func isReadable(_ path: String) -> Bool { + let parts = path.split(separator: "/") + guard !path.lowercased().hasSuffix(".pdf") else { return false } + return + (parts.count > 2 && parts[0] == "help" + && ["account", "app-store-connect", "app-review"].contains(parts[1])) + || path == "support/fee-waiver" + || path == "support/terms/apple-developer-program-license-agreement" + } + + private func quote(_ text: String) -> String { + "'" + text.replacingOccurrences(of: "'", with: "'\\''") + "'" + } +} diff --git a/Sources/CLI/renderer/SupportTextRenderer.swift b/Sources/CLI/renderer/SupportTextRenderer.swift new file mode 100644 index 0000000..507ea3b --- /dev/null +++ b/Sources/CLI/renderer/SupportTextRenderer.swift @@ -0,0 +1,170 @@ +import Foundation + +struct SupportTextRenderer { + let agent: Bool + private let layout = DocumentationTextLayout() + + func render(_ presentation: SupportPresentation) -> String { + var sections = render(presentation.payload) + if let navigation = presentation.navigation, !navigation.isEmpty { + sections.append(heading("Follow-up commands", level: 2)) + sections += navigation.map { item in + item.title + "\n" + fenced(item.command, language: "sh") + } + } + let text = sections.filter { !$0.isEmpty }.joined(separator: "\n\n") + return String( + text.unicodeScalars.filter { + !CharacterSet.controlCharacters.contains($0) || $0 == "\n" || $0 == "\t" + }) + } + + private func render(_ payload: SupportPayload) -> [String] { + switch payload { + case .articles(let value): + return header(value.header) + + value.categories.flatMap { + [heading($0.title, level: 2), $0.summary] + $0.links.map(reference) + } + case .help(let value): + return header(value.header) + value.featuredResources.flatMap(described) + + [heading(value.topicsTitle, level: 2)] + value.topics.flatMap(topic) + + described(value.glossary) + case .contents(let value): + return header(value.header) + value.entries.flatMap { contents($0, level: 2) } + case .glossary(let value): + return header(value.header) + value.entries.flatMap { [heading($0.term, level: 2), blocks($0.definition)] } + case .glossaryEntry(let value): + return [heading(value.term, level: 1), blocks(value.definition)] + case .terms(let value): + return header(value.header) + + value.categories.flatMap { + [heading($0.title, level: 2), blocks($0.introduction)] + + $0.entries.flatMap { termsEntry($0, level: 3) } + } + case .termsEntry(let value): + return termsEntry(value, level: 1) + case .article(let value): + return [ + heading(value.title, level: 1), value.url.absoluteString, value.context ?? "", blocks(value.content), + ] + + (value.related.isEmpty ? [] : [heading("Related", level: 2)] + value.related.map(reference)) + + (value.notices.isEmpty ? [] : [heading("Notices", level: 2), blocks(value.notices)]) + } + } + + private func header(_ header: SupportPageHeader) -> [String] { + [heading(header.title, level: 1), header.url.absoluteString, header.introduction] + } + + private func described(_ item: SupportDescribedLink) -> [String] { + [reference(item.link), item.summary] + } + + private func topic(_ topic: SupportHelpTopic) -> [String] { + [heading(topic.title, level: 3)] + + topic.groups.flatMap { + ($0.title.map { [heading($0, level: 4)] } ?? []) + $0.links.map(reference) + } + } + + private func contents(_ entry: SupportContentsEntry, level: Int) -> [String] { + [entry.link.map(reference) ?? heading(entry.title, level: level)] + + entry.children.flatMap { contents($0, level: level + 1) } + } + + private func termsEntry(_ entry: SupportTermsEntry, level: Int) -> [String] { + [heading(entry.title, level: level), "ID: " + entry.id, inline(entry.description)] + + entry.resources.flatMap { resource in + [reference(resource.link)] + + (resource.translations.map { + [blocks($0.notice), $0.lastUpdatedLabel.map { "Last update: " + $0 } ?? ""] + + $0.translations.map(reference) + } ?? []) + } + } + + private func heading(_ title: String, level: Int) -> String { + agent + ? String(repeating: "#", count: min(level, 6)) + " " + title + : layout.heading(title, prominent: level == 1) + } + + private func reference(_ link: SupportPageLink) -> String { + agent + ? "- [" + link.title + "](" + link.url.absoluteString + ")" + : link.title + "\n " + link.url.absoluteString + } + + func inline(_ values: [SupportInline]) -> String { + values.map { item in + switch item { + case .text(let text): return text + case .code(let text): return agent ? "`" + text + "`" : text + case .emphasis(let content): return agent ? "*" + inline(content) + "*" : inline(content) + case .strong(let content): return agent ? "**" + inline(content) + "**" : inline(content) + case .superscript(let content): return "[" + inline(content) + "]" + case .link(let label, let url): + return agent + ? "[" + inline(label) + "](" + url.absoluteString + ")" + : inline(label) + " (" + url.absoluteString + ")" + case .lineBreak: return "\n" + } + }.joined() + } + + func blocks(_ values: [SupportContentBlock]) -> String { + values.map(block).joined(separator: "\n\n") + } + + private func block(_ value: SupportContentBlock) -> String { + switch value { + case .paragraph(let content): + return agent + ? inline(content).trimmingCharacters(in: .whitespacesAndNewlines) + : layout.paragraph(inline(content), indent: "") + case .heading(let level, let text, _): return heading(text, level: level) + case .list(let ordered, let start, let items): + return items.enumerated().map { index, item in + let prefix = ordered ? "\(start + index). " : "- " + let lines = blocks(item).components(separatedBy: "\n") + return prefix + (lines.first ?? "") + lines.dropFirst().map { "\n " + $0 }.joined() + }.joined(separator: "\n") + case .codeListing(let text, let syntax): + return agent + ? fenced(text, language: syntax ?? "") + : layout.codeBlock(text.components(separatedBy: "\n"), language: syntax, indent: "") + case .aside(let style, let content): + return style.capitalized + ":\n" + blocks(content) + case .table(let rows): return table(rows) + case .image(let url, let alt, let caption): + return (agent ? "![" + alt + "](" + url.absoluteString + ")" : alt + "\n" + url.absoluteString) + + (caption.isEmpty ? "" : "\n" + inline(caption)) + case .separator: return "---" + } + } + + private func table(_ rows: [SupportTableRow]) -> String { + guard let first = rows.first else { return "" } + let lines = rows.map { row in + "| " + + row.cells.map { + blocks($0.content).replacingOccurrences(of: "\n", with: " ") + .replacingOccurrences(of: "|", with: "\\|") + }.joined(separator: " | ") + " |" + } + guard agent else { return lines.joined(separator: "\n") } + let separator = "| " + first.cells.map { _ in "---" }.joined(separator: " | ") + " |" + if first.cells.allSatisfy(\.isHeader) { + return ([lines[0], separator] + lines.dropFirst()).joined(separator: "\n") + } + let header = "| " + first.cells.map { _ in " " }.joined(separator: " | ") + " |" + return ([header, separator] + lines).joined(separator: "\n") + } + + private func fenced(_ text: String, language: String) -> String { + let longest = text.split(whereSeparator: { $0 != "`" }).map(\.count).max() ?? 0 + let fence = String(repeating: "`", count: max(3, longest + 1)) + return fence + language + "\n" + text + "\n" + fence + } +} diff --git a/Sources/CLI/support/SupportCatalogs.swift b/Sources/CLI/support/SupportCatalogs.swift index 6557819..3551238 100644 --- a/Sources/CLI/support/SupportCatalogs.swift +++ b/Sources/CLI/support/SupportCatalogs.swift @@ -1,34 +1,34 @@ import Foundation -struct SupportPageHeader: Equatable, Sendable { +struct SupportPageHeader: Encodable, Equatable, Sendable { let url: URL let title: String let introduction: String } -struct SupportPageLink: Equatable, Sendable { +struct SupportPageLink: Encodable, Equatable, Sendable { let title: String let url: URL } -struct SupportDescribedLink: Equatable, Sendable { +struct SupportDescribedLink: Encodable, Equatable, Sendable { let link: SupportPageLink let summary: String } -struct SupportArticlesCatalog: Equatable, Sendable { +struct SupportArticlesCatalog: Encodable, Equatable, Sendable { let header: SupportPageHeader var categories: [SupportArticleCategory] } -struct SupportArticleCategory: Equatable, Sendable { +struct SupportArticleCategory: Encodable, Equatable, Sendable { let id: String let title: String let summary: String let links: [SupportPageLink] } -struct SupportHelpCatalog: Equatable, Sendable { +struct SupportHelpCatalog: Encodable, Equatable, Sendable { let header: SupportPageHeader let featuredResources: [SupportDescribedLink] let topicsTitle: String @@ -36,62 +36,62 @@ struct SupportHelpCatalog: Equatable, Sendable { let glossary: SupportDescribedLink } -struct SupportHelpTopic: Equatable, Sendable { +struct SupportHelpTopic: Encodable, Equatable, Sendable { let title: String let groups: [SupportTopicLinkGroup] } -struct SupportTopicLinkGroup: Equatable, Sendable { +struct SupportTopicLinkGroup: Encodable, Equatable, Sendable { let title: String? let links: [SupportPageLink] } -struct SupportGlossary: Equatable, Sendable { +struct SupportGlossary: Encodable, Equatable, Sendable { let header: SupportPageHeader var entries: [SupportGlossaryEntry] } -struct SupportGlossaryEntry: Equatable, Sendable { +struct SupportGlossaryEntry: Encodable, Equatable, Sendable { let term: String let definition: [SupportContentBlock] } -struct SupportTermsCatalog: Equatable, Sendable { +struct SupportTermsCatalog: Encodable, Equatable, Sendable { let header: SupportPageHeader var categories: [SupportTermsCategory] } -struct SupportTermsCategory: Equatable, Sendable { +struct SupportTermsCategory: Encodable, Equatable, Sendable { let id: String let title: String let introduction: [SupportContentBlock] let entries: [SupportTermsEntry] } -struct SupportTermsEntry: Equatable, Sendable { +struct SupportTermsEntry: Encodable, Equatable, Sendable { let id: String let title: String let description: [SupportInline] let resources: [SupportTermsResource] } -struct SupportTermsResource: Equatable, Sendable { +struct SupportTermsResource: Encodable, Equatable, Sendable { let link: SupportPageLink let translations: SupportTranslationSet? } -struct SupportTranslationSet: Equatable, Sendable { +struct SupportTranslationSet: Encodable, Equatable, Sendable { let notice: [SupportContentBlock] let lastUpdatedLabel: String? let translations: [SupportPageLink] } -struct SupportGuideContents: Equatable, Sendable { +struct SupportGuideContents: Encodable, Equatable, Sendable { let header: SupportPageHeader let entries: [SupportContentsEntry] } -struct SupportContentsEntry: Equatable, Sendable { +struct SupportContentsEntry: Encodable, Equatable, Sendable { let title: String let link: SupportPageLink? let children: [SupportContentsEntry] diff --git a/Sources/CLI/support/SupportContent.swift b/Sources/CLI/support/SupportContent.swift index 95119e0..1c44959 100644 --- a/Sources/CLI/support/SupportContent.swift +++ b/Sources/CLI/support/SupportContent.swift @@ -1,6 +1,6 @@ import Foundation -indirect enum SupportInline: Equatable, Sendable { +indirect enum SupportInline: Encodable, Equatable, Sendable { case text(String) case code(String) case emphasis([SupportInline]) @@ -11,7 +11,7 @@ indirect enum SupportInline: Equatable, Sendable { case lineBreak } -indirect enum SupportContentBlock: Equatable, Sendable { +indirect enum SupportContentBlock: Encodable, Equatable, Sendable { case paragraph([SupportInline]) case heading(level: Int, text: String, anchor: String?) case list(ordered: Bool, start: Int, items: [[SupportContentBlock]]) @@ -22,18 +22,18 @@ indirect enum SupportContentBlock: Equatable, Sendable { case separator } -struct SupportTableRow: Equatable, Sendable { +struct SupportTableRow: Encodable, Equatable, Sendable { let cells: [SupportTableCell] } -struct SupportTableCell: Equatable, Sendable { +struct SupportTableCell: Encodable, Equatable, Sendable { let content: [SupportContentBlock] let isHeader: Bool let columnSpan: Int let rowSpan: Int } -struct SupportArticle: Equatable, Sendable { +struct SupportArticle: Encodable, Equatable, Sendable { let url: URL let title: String let context: String? diff --git a/Tests/CLITests/renderer/SupportRendererTests.swift b/Tests/CLITests/renderer/SupportRendererTests.swift new file mode 100644 index 0000000..e94bd8d --- /dev/null +++ b/Tests/CLITests/renderer/SupportRendererTests.swift @@ -0,0 +1,121 @@ +import Foundation +import Testing + +@testable import CLI + +@Suite("Support presentation and output") +struct SupportRendererTests { + @Test("JSON preserves semantic glossary content and includes navigation only for agents") + func structuredGlossary() throws { + // -- Arrange -- + let entry = SupportGlossaryEntry( + term: "Account Holder", + definition: [ + .paragraph([ + .text("The "), .emphasis([.text("owner")]), .text("."), + ]) + ]) + let value = SupportPayload.glossaryEntry(entry) + let human = DefaultSupportRenderer(output: .json, audience: .human) + let agent = DefaultSupportRenderer(output: .json, audience: .agent) + + // -- Act -- + let humanJSON = try object(human.render(value)) + let agentJSON = try object(agent.render(value)) + + // -- Assert -- + #expect(humanJSON["kind"] as? String == "glossaryEntry") + #expect(humanJSON["term"] as? String == "Account Holder") + #expect(humanJSON["navigation"] == nil) + let blocks = try #require(humanJSON["definition"] as? [[String: Any]]) + #expect(blocks.first?["type"] as? String == "paragraph") + let navigation = try #require(agentJSON["navigation"] as? [[String: Any]]) + #expect( + navigation.first?["command"] as? String + == "apple-docs support glossary view --term 'Account Holder' --agent") + } + + @Test("follow-up commands quote names and omit unsupported PDF destinations") + func navigation() throws { + // -- Arrange -- + let header = SupportPageHeader( + url: URL(string: "https://developer.apple.com/support/articles/")!, + title: "Articles", introduction: "Support resources.") + let payload = SupportPayload.articles( + SupportArticlesCatalog( + header: header, + categories: [ + SupportArticleCategory( + id: "membership", title: "Membership", summary: "Account resources.", + links: [ + SupportPageLink( + title: "Fee waiver", + url: URL(string: "https://developer.apple.com/support/fee-waiver/")!), + SupportPageLink( + title: "PDF", url: URL(string: "https://developer.apple.com/support/guide.pdf")!), + ]) + ])) + + // -- Act -- + let text = try DefaultSupportRenderer(output: .text, audience: .agent).render(payload) + let presentation = SupportPresenter().present( + .glossaryEntry( + SupportGlossaryEntry(term: "Developer's account", definition: [])), audience: .agent) + + // -- Assert -- + #expect(text.contains("# Articles")) + #expect(text.contains("https://developer.apple.com/support/guide.pdf")) + #expect(text.contains("apple-docs support view --path 'support/fee-waiver' --agent")) + #expect(!text.contains("--path 'support/guide.pdf'")) + #expect(presentation.navigation?.first?.command.contains("'Developer'\\''s account'") == true) + } + + @Test("human rendering keeps table contents, code whitespace and legal notices") + func humanDocument() throws { + // -- Arrange -- + let payload = SupportPayload.article( + SupportArticle( + url: URL(string: "https://developer.apple.com/support/example/")!, title: "Example", context: "Support", + content: [ + .heading(level: 2, text: "Details", anchor: "details"), + .table([ + SupportTableRow(cells: [ + SupportTableCell( + content: [.paragraph([.text("No alpha")])], + isHeader: false, columnSpan: 1, rowSpan: 1) + ]) + ]), + .codeListing("let value = 1\n print(value)", syntax: "swift"), + ], related: [], + notices: [.paragraph([.text("The accepted version is binding.")])])) + + // -- Act -- + let text = try DefaultSupportRenderer(output: .text, audience: .human).render(payload) + + // -- Assert -- + #expect(text.contains("Example\n")) + #expect(text.contains("No alpha")) + #expect(text.contains(" print(value)")) + #expect(text.contains("The accepted version is binding.")) + #expect(!text.contains("apple-docs support")) + } + + @Test("terminal output removes control sequences from external page text") + func removesControls() throws { + // -- Arrange -- + let payload = SupportPayload.glossaryEntry( + SupportGlossaryEntry( + term: "Term\u{001B}[2J", definition: [.paragraph([.text("Text\u{0007}")])])) + + // -- Act -- + let text = try DefaultSupportRenderer(output: .text, audience: .human).render(payload) + + // -- Assert -- + #expect(!text.contains("\u{001B}")) + #expect(!text.contains("\u{0007}")) + } + + private func object(_ json: String) throws -> [String: Any] { + try #require(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any]) + } +} From 205a43125cf1576fc3a80ca987022143df831038 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 15:38:17 +0100 Subject: [PATCH 2/4] fix(support): Render inline images and large list ordinals --- .../CLI/renderer/SupportContentEncoding.swift | 6 +- .../CLI/renderer/SupportTextRenderer.swift | 6 +- .../SupportRichContentRenderingTests.swift | 95 +++++++++++++++++++ 3 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 Tests/CLITests/renderer/SupportRichContentRenderingTests.swift diff --git a/Sources/CLI/renderer/SupportContentEncoding.swift b/Sources/CLI/renderer/SupportContentEncoding.swift index 2069a0e..0f269b1 100644 --- a/Sources/CLI/renderer/SupportContentEncoding.swift +++ b/Sources/CLI/renderer/SupportContentEncoding.swift @@ -1,11 +1,15 @@ import Foundation extension SupportInline { - private enum CodingKeys: CodingKey { case type, text, content, label, url } + private enum CodingKeys: CodingKey { case type, text, content, label, url, alt } func encode(to encoder: any Encoder) throws { var container = encoder.container(keyedBy: CodingKeys.self) switch self { + case .image(let url, let alt): + try container.encode("image", forKey: .type) + try container.encode(url, forKey: .url) + try container.encode(alt, forKey: .alt) case .text(let text): try container.encode("text", forKey: .type) try container.encode(text, forKey: .text) diff --git a/Sources/CLI/renderer/SupportTextRenderer.swift b/Sources/CLI/renderer/SupportTextRenderer.swift index 507ea3b..d434491 100644 --- a/Sources/CLI/renderer/SupportTextRenderer.swift +++ b/Sources/CLI/renderer/SupportTextRenderer.swift @@ -99,6 +99,8 @@ struct SupportTextRenderer { func inline(_ values: [SupportInline]) -> String { values.map { item in switch item { + case .image(let url, let alt): + return agent ? "![" + alt + "](" + url.absoluteString + ")" : alt + " (" + url.absoluteString + ")" case .text(let text): return text case .code(let text): return agent ? "`" + text + "`" : text case .emphasis(let content): return agent ? "*" + inline(content) + "*" : inline(content) @@ -126,7 +128,9 @@ struct SupportTextRenderer { case .heading(let level, let text, _): return heading(text, level: level) case .list(let ordered, let start, let items): return items.enumerated().map { index, item in - let prefix = ordered ? "\(start + index). " : "- " + let prefix = + ordered + ? NSDecimalNumber(decimal: Decimal(start) + Decimal(index)).stringValue + ". " : "- " let lines = blocks(item).components(separatedBy: "\n") return prefix + (lines.first ?? "") + lines.dropFirst().map { "\n " + $0 }.joined() }.joined(separator: "\n") diff --git a/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift new file mode 100644 index 0000000..9a237c2 --- /dev/null +++ b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift @@ -0,0 +1,95 @@ +import Foundation +import Testing + +@testable import CLI + +@Suite("Support rich content rendering") +struct SupportRichContentRenderingTests { + @Test( + "renders linked inline images without losing text or either URL", + arguments: [ + OutputAudience.human, .agent, + ]) + func rendersInlineImages(audience: OutputAudience) throws { + // -- Arrange -- + let payload = try payload( + """ +

Before Example after.

+ """) + let renderer = DefaultSupportRenderer(output: .text, audience: audience) + + // -- Act -- + let output = try renderer.render(payload) + + // -- Assert -- + if audience == .agent { + #expect( + output.contains( + "Before [![Example](https://developer.apple.com/images/example.png)]" + + "(https://developer.apple.com/support/details/) after.")) + } else { + #expect(output.contains("Before Example")) + #expect(output.contains("https://developer.apple.com/images/example.png")) + #expect(output.contains("https://developer.apple.com/support/details/")) + #expect(output.contains("after.")) + } + } + + @Test("JSON preserves inline image metadata inside its enclosing link") + func encodesInlineImages() throws { + // -- Arrange -- + let payload = try payload( + """ +

Before Example after.

+ """) + let renderer = DefaultSupportRenderer(output: .json, audience: .human) + + // -- Act -- + let output = try renderer.render(payload) + let json = try #require(JSONSerialization.jsonObject(with: Data(output.utf8)) as? [String: Any]) + let blocks = try #require(json["content"] as? [[String: Any]]) + let inline = try #require(blocks.first?["content"] as? [[String: Any]]) + let label = try #require(inline[1]["label"] as? [[String: Any]]) + let image = try #require(label.first) + + // -- Assert -- + #expect(inline[0]["text"] as? String == "Before ") + #expect(inline[1]["url"] as? String == "https://developer.apple.com/support/details/") + #expect(image["type"] as? String == "image") + #expect(image["url"] as? String == "https://developer.apple.com/images/example.png") + #expect(image["alt"] as? String == "Example") + #expect(inline[2]["text"] as? String == " after.") + } + + @Test( + "ordered lists preserve exact numbering across integer boundaries", + arguments: [ + ("9223372036854775807", "9223372036854775807. First\n9223372036854775808. Second"), + ("3", "3. First\n4. Second"), + ("-1", "-1. First\n0. Second"), + ("-9223372036854775808", "-9223372036854775808. First\n-9223372036854775807. Second"), + ]) + func rendersLargeListNumbers(start: String, expected: String) throws { + // -- Arrange -- + let payload = try payload("
  1. First
  2. Second
") + let human = DefaultSupportRenderer(output: .text, audience: .human) + let agent = DefaultSupportRenderer(output: .text, audience: .agent) + + // -- Act -- + let humanOutput = try human.render(payload) + let agentOutput = try agent.render(payload) + + // -- Assert -- + #expect(humanOutput.contains(expected)) + #expect(agentOutput.contains(expected)) + } + + private func payload(_ content: String) throws -> SupportPayload { + let html = "

Example

" + content + "
" + let parser = try SupportHTMLParser( + document: SupportHTMLDocument( + destination: SupportDestination(path: "support/example"), html: html, responseByteCount: html.utf8.count + )) + return try .article(parser.article()) + } +} From e6a600ad4290cd82c4bd00642138b26d2d410494 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 16:06:51 +0100 Subject: [PATCH 3/4] fix(support): Preserve explicit paragraph line breaks --- Sources/CLI/renderer/SupportTextRenderer.swift | 5 +++-- .../SupportRichContentRenderingTests.swift | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/Sources/CLI/renderer/SupportTextRenderer.swift b/Sources/CLI/renderer/SupportTextRenderer.swift index d434491..57143d2 100644 --- a/Sources/CLI/renderer/SupportTextRenderer.swift +++ b/Sources/CLI/renderer/SupportTextRenderer.swift @@ -122,9 +122,10 @@ struct SupportTextRenderer { private func block(_ value: SupportContentBlock) -> String { switch value { case .paragraph(let content): + let text = inline(content) return agent - ? inline(content).trimmingCharacters(in: .whitespacesAndNewlines) - : layout.paragraph(inline(content), indent: "") + ? text.trimmingCharacters(in: .whitespacesAndNewlines) + : text.components(separatedBy: "\n").map { layout.paragraph($0, indent: "") }.joined(separator: "\n") case .heading(let level, let text, _): return heading(text, level: level) case .list(let ordered, let start, let items): return items.enumerated().map { index, item in diff --git a/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift index 9a237c2..1ac4e95 100644 --- a/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift +++ b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift @@ -61,6 +61,22 @@ struct SupportRichContentRenderingTests { #expect(inline[2]["text"] as? String == " after.") } + @Test("explicit paragraph line breaks are preserved for both audiences") + func preservesParagraphLineBreaks() throws { + // -- Arrange -- + let payload = try payload("

First
Second

Fourth.

") + let human = DefaultSupportRenderer(output: .text, audience: .human) + let agent = DefaultSupportRenderer(output: .text, audience: .agent) + + // -- Act -- + let humanOutput = try human.render(payload) + let agentOutput = try agent.render(payload) + + // -- Assert -- + #expect(humanOutput.contains("First\nSecond\n\nFourth.")) + #expect(agentOutput.contains("First\nSecond\n\nFourth.")) + } + @Test( "ordered lists preserve exact numbering across integer boundaries", arguments: [ From aea867d09905789222565defc4b1acd7561d01fa Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 16:32:19 +0100 Subject: [PATCH 4/4] fix(support): Preserve Markdown structure and literal content --- .../CLI/renderer/SupportTextRenderer.swift | 43 +++++---- .../SupportMarkdownRenderingTests.swift | 91 +++++++++++++++++++ .../SupportRichContentRenderingTests.swift | 23 ++++- 3 files changed, 138 insertions(+), 19 deletions(-) create mode 100644 Tests/CLITests/renderer/SupportMarkdownRenderingTests.swift diff --git a/Sources/CLI/renderer/SupportTextRenderer.swift b/Sources/CLI/renderer/SupportTextRenderer.swift index 57143d2..5b5117e 100644 --- a/Sources/CLI/renderer/SupportTextRenderer.swift +++ b/Sources/CLI/renderer/SupportTextRenderer.swift @@ -3,13 +3,14 @@ import Foundation struct SupportTextRenderer { let agent: Bool private let layout = DocumentationTextLayout() + private let markdown = DocumentationContentRenderer(audience: .agent) func render(_ presentation: SupportPresentation) -> String { var sections = render(presentation.payload) if let navigation = presentation.navigation, !navigation.isEmpty { sections.append(heading("Follow-up commands", level: 2)) sections += navigation.map { item in - item.title + "\n" + fenced(item.command, language: "sh") + plain(item.title) + "\n" + fenced(item.command, language: "sh") } } let text = sections.filter { !$0.isEmpty }.joined(separator: "\n\n") @@ -24,7 +25,7 @@ struct SupportTextRenderer { case .articles(let value): return header(value.header) + value.categories.flatMap { - [heading($0.title, level: 2), $0.summary] + $0.links.map(reference) + [heading($0.title, level: 2), plain($0.summary)] + $0.links.map(reference) } case .help(let value): return header(value.header) + value.featuredResources.flatMap(described) @@ -46,7 +47,8 @@ struct SupportTextRenderer { return termsEntry(value, level: 1) case .article(let value): return [ - heading(value.title, level: 1), value.url.absoluteString, value.context ?? "", blocks(value.content), + heading(value.title, level: 1), value.url.absoluteString, plain(value.context ?? ""), + blocks(value.content), ] + (value.related.isEmpty ? [] : [heading("Related", level: 2)] + value.related.map(reference)) + (value.notices.isEmpty ? [] : [heading("Notices", level: 2), blocks(value.notices)]) @@ -54,11 +56,11 @@ struct SupportTextRenderer { } private func header(_ header: SupportPageHeader) -> [String] { - [heading(header.title, level: 1), header.url.absoluteString, header.introduction] + [heading(header.title, level: 1), header.url.absoluteString, plain(header.introduction)] } private func described(_ item: SupportDescribedLink) -> [String] { - [reference(item.link), item.summary] + [reference(item.link), plain(item.summary)] } private func topic(_ topic: SupportHelpTopic) -> [String] { @@ -74,25 +76,29 @@ struct SupportTextRenderer { } private func termsEntry(_ entry: SupportTermsEntry, level: Int) -> [String] { - [heading(entry.title, level: level), "ID: " + entry.id, inline(entry.description)] + [heading(entry.title, level: level), "ID: " + plain(entry.id), inline(entry.description)] + entry.resources.flatMap { resource in [reference(resource.link)] + (resource.translations.map { - [blocks($0.notice), $0.lastUpdatedLabel.map { "Last update: " + $0 } ?? ""] + [blocks($0.notice), $0.lastUpdatedLabel.map { "Last update: " + plain($0) } ?? ""] + $0.translations.map(reference) } ?? []) } } + private func plain(_ text: String) -> String { + agent ? markdown.markdown(text) : text + } + private func heading(_ title: String, level: Int) -> String { agent - ? String(repeating: "#", count: min(level, 6)) + " " + title + ? String(repeating: "#", count: min(level, 6)) + " " + plain(title) : layout.heading(title, prominent: level == 1) } private func reference(_ link: SupportPageLink) -> String { agent - ? "- [" + link.title + "](" + link.url.absoluteString + ")" + ? "- " + markdown.link(plain(link.title), target: .external(link.url)) : link.title + "\n " + link.url.absoluteString } @@ -100,15 +106,16 @@ struct SupportTextRenderer { values.map { item in switch item { case .image(let url, let alt): - return agent ? "![" + alt + "](" + url.absoluteString + ")" : alt + " (" + url.absoluteString + ")" - case .text(let text): return text - case .code(let text): return agent ? "`" + text + "`" : text + return agent + ? "!" + markdown.link(plain(alt), target: .external(url)) : alt + " (" + url.absoluteString + ")" + case .text(let text): return plain(text) + case .code(let text): return agent ? markdown.inlineCode(text) : text case .emphasis(let content): return agent ? "*" + inline(content) + "*" : inline(content) case .strong(let content): return agent ? "**" + inline(content) + "**" : inline(content) - case .superscript(let content): return "[" + inline(content) + "]" + case .superscript(let content): return plain("[") + inline(content) + plain("]") case .link(let label, let url): return agent - ? "[" + inline(label) + "](" + url.absoluteString + ")" + ? markdown.link(inline(label), target: .external(url)) : inline(label) + " (" + url.absoluteString + ")" case .lineBreak: return "\n" } @@ -133,17 +140,19 @@ struct SupportTextRenderer { ordered ? NSDecimalNumber(decimal: Decimal(start) + Decimal(index)).stringValue + ". " : "- " let lines = blocks(item).components(separatedBy: "\n") - return prefix + (lines.first ?? "") + lines.dropFirst().map { "\n " + $0 }.joined() + let continuation = String(repeating: " ", count: prefix.count) + return prefix + (lines.first ?? "") + + lines.dropFirst().map { $0.isEmpty ? "\n" : "\n" + continuation + $0 }.joined() }.joined(separator: "\n") case .codeListing(let text, let syntax): return agent ? fenced(text, language: syntax ?? "") : layout.codeBlock(text.components(separatedBy: "\n"), language: syntax, indent: "") case .aside(let style, let content): - return style.capitalized + ":\n" + blocks(content) + return plain(style.capitalized) + ":\n" + blocks(content) case .table(let rows): return table(rows) case .image(let url, let alt, let caption): - return (agent ? "![" + alt + "](" + url.absoluteString + ")" : alt + "\n" + url.absoluteString) + return (agent ? "!" + markdown.link(plain(alt), target: .external(url)) : alt + "\n" + url.absoluteString) + (caption.isEmpty ? "" : "\n" + inline(caption)) case .separator: return "---" } diff --git a/Tests/CLITests/renderer/SupportMarkdownRenderingTests.swift b/Tests/CLITests/renderer/SupportMarkdownRenderingTests.swift new file mode 100644 index 0000000..5fb9e02 --- /dev/null +++ b/Tests/CLITests/renderer/SupportMarkdownRenderingTests.swift @@ -0,0 +1,91 @@ +import Foundation +import Testing + +@testable import CLI + +@Suite("Support Markdown rendering") +struct SupportMarkdownRenderingTests { + @Test("agent text escapes Markdown syntax without changing human text") + func escapesText() throws { + // -- Arrange -- + let text = #"Read *literal* [label] \path"# + let payload = SupportPayload.glossaryEntry( + SupportGlossaryEntry( + term: "Example", definition: [.paragraph([.text(text)])])) + + // -- Act -- + let agent = try DefaultSupportRenderer(output: .text, audience: .agent).render(payload) + let human = try DefaultSupportRenderer(output: .text, audience: .human).render(payload) + + // -- Assert -- + #expect(agent.contains(#"Read \*literal\* \[label\] \ \\path"#)) + #expect(human.contains(text)) + } + + @Test( + "code span delimiters cannot be closed by literal backticks", + arguments: [ + ("value`name", "``value`name``"), + ("`value`", "`` `value` ``"), + ("value``name", "```value``name```"), + ]) + func preservesCodeSpans(source: String, expected: String) throws { + // -- Arrange -- + let payload = SupportPayload.glossaryEntry( + SupportGlossaryEntry( + term: "Example", definition: [.paragraph([.code(source)])])) + + // -- Act -- + let output = try DefaultSupportRenderer(output: .text, audience: .agent).render(payload) + + // -- Assert -- + #expect(output.contains(expected)) + } + + @Test("link and image destinations with parentheses remain enclosed") + func enclosesDestinations() throws { + // -- Arrange -- + let url = try #require(URL(string: "https://developer.apple.com/support/example_(detail)/")) + let payload = SupportPayload.glossaryEntry( + SupportGlossaryEntry( + term: "Example", + definition: [ + .paragraph([ + .link(label: [.text("[Details]")], url: url), + .image(url: url, alt: "[Diagram]"), + ]), .image(url: url, alt: "[Block diagram]", caption: []), + ])) + + // -- Act -- + let output = try DefaultSupportRenderer(output: .text, audience: .agent).render(payload) + + // -- Assert -- + #expect(output.contains(#"[\[Details\]]()"#)) + #expect(output.contains(#"![\[Diagram\]]()"#)) + #expect(output.contains(#"![\[Block diagram\]]()"#)) + } + + @Test("catalog titles, summaries and references escape external Markdown syntax") + func escapesCatalogText() throws { + // -- Arrange -- + let url = try #require(URL(string: "https://developer.apple.com/support/example_(detail)/")) + let payload = SupportPayload.articles( + SupportArticlesCatalog( + header: SupportPageHeader(url: url, title: "Support [Guide]", introduction: "Read *first*."), + categories: [ + SupportArticleCategory( + id: "example", title: "Literal *category*", summary: "Use .", + links: [SupportPageLink(title: "[Open]", url: url)]) + ])) + + // -- Act -- + let output = try DefaultSupportRenderer(output: .text, audience: .agent).render(payload) + + // -- Assert -- + #expect(output.contains(#"# Support \[Guide\]"#)) + #expect(output.contains(#"Read \*first\*."#)) + #expect(output.contains(#"## Literal \*category\*"#)) + #expect(output.contains(#"Use \."#)) + #expect(output.contains(#"- [\[Open\]]()"#)) + } +} diff --git a/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift index 1ac4e95..df46b1c 100644 --- a/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift +++ b/Tests/CLITests/renderer/SupportRichContentRenderingTests.swift @@ -25,8 +25,8 @@ struct SupportRichContentRenderingTests { if audience == .agent { #expect( output.contains( - "Before [![Example](https://developer.apple.com/images/example.png)]" - + "(https://developer.apple.com/support/details/) after.")) + "Before [![Example]()]" + + "() after.")) } else { #expect(output.contains("Before Example")) #expect(output.contains("https://developer.apple.com/images/example.png")) @@ -100,6 +100,25 @@ struct SupportRichContentRenderingTests { #expect(agentOutput.contains(expected)) } + @Test("ordered list continuation blocks align with each marker's content column") + func alignsOrderedListContinuations() throws { + // -- Arrange -- + let payload = try payload( + """ +
    +
  1. First

    Second

    • Child
  2. +
  3. Next

    More

  4. +
+ """) + let renderer = DefaultSupportRenderer(output: .text, audience: .agent) + + // -- Act -- + let output = try renderer.render(payload) + + // -- Assert -- + #expect(output.contains("9. First\n\n Second\n\n - Child\n10. Next\n\n More")) + } + private func payload(_ content: String) throws -> SupportPayload { let html = "

Example

" + content + "
" let parser = try SupportHTMLParser(