Commit `a9bc9a9685`

a9bc9a9685c4a8716fdd08b81ee503469282a61d

parent: bec396ade8

Unsigned

cmc <hello@cleberg.net> · 2026-08-31 17:28 UTC

Resolve URLs and number footnotes in the native renderer

OrgAttributedStringRenderer emitted `.file` targets as raw relative paths
and footnote references as their label, so a README rendered natively got
broken links and unnumbered notes where the HTML one did not. It now takes
OrgRenderOptions and shares OrgURLResolver and OrgFootnotes with the HTML
renderer, so both resolve, sanitize and number identically.

OrgRenderOptions is Sendable, which it always was in practice.

Layout: unified · split

Sources/OrgSwift/AST/OrgAttributedStringRenderer.swift +26 −25

		@@ -7,11 +7,26 @@ import Foundation
7	7	/// not a second parser. It stays Foundation-only (no SwiftUI), so it is usable anywhere; a
8	8	/// SwiftUI block renderer would sit on top, using this for the inline runs inside each block.
9	9	public struct OrgAttributedStringRenderer: Sendable {
	10	/// Resolution options, so repository-relative links resolve exactly as they do in HTML.
	11	public var options: OrgRenderOptions
10	12
11		public init() {}
	13	public init(options: OrgRenderOptions = .init()) {
	14	self.options = options
	15	}
	16
	17	private var resolver: OrgURLResolver { OrgURLResolver(options: options) }
12	18
13	19	/// Render one run of inline objects, carrying intents a UI layer can style.
	20	///
	21	/// Footnote numbering is document-wide, so a caller rendering a whole document threads
	22	/// its own ``OrgFootnotes`` through ``inline(_:_:)``; this overload numbers within the
	23	/// run it is given.
14	24	public func inline(_ objects: [OrgObject]) -> AttributedString {
	25	var notes = OrgFootnotes(document: OrgDocument())
	26	return inline(objects, &notes)
	27	}
	28
	29	package func inline(_ objects: [OrgObject], _ notes: inout OrgFootnotes) -> AttributedString {
15	30	var result = AttributedString()
16	31	for object in objects {
17	32	switch object {
		@@ -19,12 +34,12 @@ public struct OrgAttributedStringRenderer: Sendable {
19	34	result += AttributedString(text)
20	35
21	36	case .bold(let children):
22		var part = inline(children)
	37	var part = inline(children, &notes)
23	38	part.inlinePresentationIntent = .stronglyEmphasized
24	39	result += part
25	40
26	41	case .italic(let children):
27		var part = inline(children)
	42	var part = inline(children, &notes)
28	43	part.inlinePresentationIntent = .emphasized
29	44	result += part
30	45
		@@ -32,12 +47,12 @@ public struct OrgAttributedStringRenderer: Sendable {
32	47	// underlineStyle/strikethroughStyle keys live in the UIKit/AppKit scopes), so they
33	48	// travel as roles the UI layer applies.
34	49	case .underline(let children):
35		var part = inline(children)
	50	var part = inline(children, &notes)
36	51	part.orgRole = .underline
37	52	result += part
38	53
39	54	case .strikeThrough(let children):
40		var part = inline(children)
	55	var part = inline(children, &notes)
41	56	part.orgRole = .strikeThrough
42	57	result += part
43	58
		@@ -48,7 +63,7 @@ public struct OrgAttributedStringRenderer: Sendable {
48	63
49	64	case .superscript(let children):
50	65	// No portable superscript attribute; mark it so a UI layer can raise it.
51		var part = inline(children)
	66	var part = inline(children, &notes)
52	67	part.orgRole = .superscript
53	68	result += part
54	69
		@@ -60,8 +75,8 @@ public struct OrgAttributedStringRenderer: Sendable {
60	75	part.orgRole = .timestamp
61	76	result += part
62	77
63		case .footnoteRef(let label, _):
64		var part = AttributedString("[\(label)]")
	78	case .footnoteRef(let label, let inlineNote):
	79	var part = AttributedString("[\(notes.number(for: label, inline: inlineNote))]")
65	80	part.orgRole = .footnoteReference
66	81	result += part
67	82
		@@ -71,8 +86,9 @@ public struct OrgAttributedStringRenderer: Sendable {
71	86	result += part
72	87
73	88	case .link(let link):
74		var part = link.description.map { inline($0) } ?? AttributedString(displayValue(link.target))
75		if let url = URL(string: hrefValue(link.target)) {
	89	var part = link.description.map { inline($0, &notes) }
	90	?? AttributedString(resolver.displayValue(link.target))
	91	if let href = resolver.href(for: link.target), let url = URL(string: href) {
76	92	part.link = url
77	93	}
78	94	result += part
		@@ -93,21 +109,6 @@ public struct OrgAttributedStringRenderer: Sendable {
93	109	}
94	110	}
95	111
96		private func hrefValue(_ target: OrgLinkTarget) -> String {
97		switch target {
98		case .external(let url): return url
99		case .file(let path): return path
100		case .id(let identifier): return "#\(identifier)"
101		}
102		}
103
104		private func displayValue(_ target: OrgLinkTarget) -> String {
105		switch target {
106		case .external(let url): return url
107		case .file(let path): return path
108		case .id(let identifier): return identifier
109		}
110		}
111	112	}
112	113
113	114	// MARK: - Custom attribute

Sources/OrgSwift/OrgRenderer.swift +1 −1

		@@ -19,7 +19,7 @@ public struct PlainCodeHighlighter: CodeHighlighter {
19	19	/// sources are rewritten to `{host}/{owner}/{repositoryName}/blob/{ref}/...`.
20	20	/// When either is nil, relative links are left as-is (and dropped by the
21	21	/// URL-scheme allowlist, which only permits absolute http/https/mailto).
22		public struct OrgRenderOptions {
	22	public struct OrgRenderOptions: Sendable {
23	23	/// Host used to build absolute URLs for repository-relative links.
24	24	public var host: String
25	25	/// Repository owner (e.g. `~ccleberg`). Nil disables relative-link resolution.

Tests/OrgSwiftTests/OrgTreeTests.swift +43

		@@ -122,6 +122,49 @@ struct ASTRendererTests {
122	122	#expect(linkRun?.link?.absoluteString == "https://example.com")
123	123	}
124	124
	125	/// The native renderer resolves and sanitizes exactly as the HTML one does, so a README
	126	/// rendered natively gets the same working links rather than raw relative paths.
	127	@Test
	128	func attributedStringResolvesRelativeLinksAndRejectsUnsafeOnes() {
	129	let renderer = OrgAttributedStringRenderer(options: OrgRenderOptions(
	130	host: "gitbay.org",
	131	owner: "krz",
	132	repositoryName: "org-swift",
	133	ref: "HEAD",
	134	readmePath: "README.org"
	135	))
	136
	137	let relative = renderer.inline(OrgParser.parseInline("[[./ARCHITECTURE.md][notes]]"))
	138	#expect(relative.runs.first { $0.link != nil }?.link?.absoluteString
	139	== "https://gitbay.org/krz/org-swift/blob/HEAD/ARCHITECTURE.md")
	140
	141	// Without repository context there is nothing to resolve against, so an unsafe
	142	// scheme reaches the allowlist and the link degrades to its text — as in HTML.
	143	let unsafe = OrgAttributedStringRenderer().inline(OrgParser.parseInline("[[javascript:alert(1)][tap]]"))
	144	#expect(String(unsafe.characters) == "tap")
	145	#expect(unsafe.runs.allSatisfy { $0.link == nil })
	146	#expect(!OrgRenderer.renderToHTML("[[javascript:alert(1)][tap]]").lowercased().contains("javascript:"))
	147	}
	148
	149	/// Footnote numbering is document-wide and order-of-use, and now shared with HTML, so
	150	/// both renderers agree on which note is number 1.
	151	@Test
	152	func attributedStringNumbersFootnotesInReferenceOrder() {
	153	let doc = OrgParser.parse("""
	154	First[fn:b] then second[fn:a] then first again[fn:b].
	155
	156	[fn:a] note a
	157	[fn:b] note b
	158	""")
	159	guard case .paragraph(let objects) = doc.elements[0] else {
	160	Issue.record("expected a paragraph"); return
	161	}
	162	var notes = OrgFootnotes(document: doc)
	163	let text = String(OrgAttributedStringRenderer().inline(objects, &notes).characters)
	164	#expect(text == "First[1] then second[2] then first again[1].")
	165	#expect(notes.notes.map(\.label) == ["b", "a"])
	166	}
	167
125	168	@Test
126	169	func attributedStringCarriesRolesForNonStandardIntents() {
127	170	let objects = OrgParser.parseInline("x^2 and <2024-01-15 Mon>")

Commit a9bc9a9685

Commit `a9bc9a9685`