Repository Public
1// ORIX DJ2// File: App/Sources/Features/Docs/Markdown.swift3// Description: A small, forgiving Markdown parser for the offline documentation and for Claude's answers: headings,4// paragraphs, lists, block quotes, rules, tables and fenced code, with inline code, emphasis and links.5// Malformed input never fails: anything that is not recognised is kept as plain text.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation1011indirect enum MDInline: Equatable, Sendable {12 case text(String)13 case code(String)14 case strong([MDInline])15 case emphasis([MDInline])16 case link([MDInline], String)17 case lineBreak1819 /// The text without any markup.20 var plain: String {21 switch self {22 case let .text(s), let .code(s): s23 case let .strong(c), let .emphasis(c), let .link(c, _): c.map(\.plain).joined()24 case .lineBreak: " "25 }26 }27}2829enum MDAlignment: Sendable, Equatable { case leading, center, trailing }3031struct MDListItem: Equatable, Sendable {32 var marker: String33 var nodes: [MDNode]34}3536indirect enum MDBlock: Equatable, Sendable {37 case heading(level: Int, text: [MDInline], anchor: String)38 case paragraph([MDInline])39 case code(language: String, text: String)40 case quote([MDNode])41 case list(ordered: Bool, items: [MDListItem])42 case table(header: [[MDInline]], alignments: [MDAlignment], rows: [[[MDInline]]])43 case rule44}4546struct MDNode: Identifiable, Equatable, Sendable {47 var id: Int48 /// First source line of the block (1-based) and the last one, for search results that scroll to their match.49 var line: Int50 var lastLine: Int51 var block: MDBlock52}5354struct MarkdownDocument: Sendable, Equatable {55 var nodes: [MDNode] = []5657 /// Every heading of the document, in order, including nested ones.58 var headings: [(level: Int, title: String, anchor: String, id: Int)] {59 var out: [(Int, String, String, Int)] = []60 func walk(_ nodes: [MDNode]) {61 for n in nodes {62 switch n.block {63 case let .heading(level, text, anchor): out.append((level, text.map(\.plain).joined(), anchor, n.id))64 case let .quote(children): walk(children)65 case let .list(_, items): for i in items { walk(i.nodes) }66 default: break67 }68 }69 }70 walk(nodes)71 return out72 }7374 /// Destinations of every link, in order.75 var links: [(title: String, destination: String)] {76 var out: [(String, String)] = []77 func inlines(_ list: [MDInline]) {78 for i in list {79 switch i {80 case let .link(children, dest): out.append((children.map(\.plain).joined(), dest))81 case let .strong(c), let .emphasis(c): inlines(c)82 default: break83 }84 }85 }86 func walk(_ nodes: [MDNode]) {87 for n in nodes {88 switch n.block {89 case let .heading(_, text, _): inlines(text)90 case let .paragraph(text): inlines(text)91 case let .quote(children): walk(children)92 case let .list(_, items): for i in items { walk(i.nodes) }93 case let .table(header, _, rows): header.forEach(inlines); rows.forEach { $0.forEach(inlines) }94 default: break95 }96 }97 }98 walk(nodes)99 return out100 }101102 /// The top-level block that contains a source line.103 func node(containingLine line: Int) -> MDNode? {104 nodes.last { $0.line <= line } ?? nodes.first105 }106107 /// All fenced code blocks, in order, with the identifier of the node that holds them.108 var codeBlocks: [(id: Int, topLevelID: Int, language: String, text: String)] {109 var out: [(Int, Int, String, String)] = []110 func walk(_ nodes: [MDNode], top: Int?) {111 for n in nodes {112 switch n.block {113 case let .code(language, text): out.append((n.id, top ?? n.id, language, text))114 case let .quote(children): walk(children, top: top ?? n.id)115 case let .list(_, items): for i in items { walk(i.nodes, top: top ?? n.id) }116 default: break117 }118 }119 }120 walk(nodes, top: nil)121 return out122 }123}124125struct MarkdownParser {126 private struct Line { var text: String; var number: Int }127128 private var nextID = 0129 private var anchors: [String: Int] = [:]130 private var depth = 0131132 static func parse(_ source: String) -> MarkdownDocument {133 var parser = MarkdownParser()134 let normalised = source.replacingOccurrences(of: "\r\n", with: "\n").replacingOccurrences(of: "\r", with: "\n")135 let lines = normalised.components(separatedBy: "\n").enumerated().map { Line(text: $0.element.replacingOccurrences(of: "\t", with: " "), number: $0.offset + 1) }136 return MarkdownDocument(nodes: parser.blocks(lines))137 }138139 /// GitHub-style anchor of a heading: lower case, spaces to hyphens, punctuation dropped.140 static func slug(_ title: String) -> String {141 var out = ""142 for c in title.lowercased() {143 if c.isLetter || c.isNumber || c == "_" || c == "-" { out.append(c) } else if c == " " { out.append("-") }144 }145 return out146 }147148 private mutating func makeID() -> Int { nextID += 1; return nextID }149150 private mutating func uniqueAnchor(_ title: String) -> String {151 let base = Self.slug(title)152 let n = anchors[base, default: 0]153 anchors[base] = n + 1154 return n == 0 ? base : "\(base)-\(n)"155 }156157 // MARK: Line classification158159 private static func indent(_ s: String) -> Int { s.prefix { $0 == " " }.count }160 private static func isBlank(_ s: String) -> Bool { s.allSatisfy { $0 == " " } }161162 private static func fence(_ s: String) -> (marker: Character, count: Int, info: String, indent: Int)? {163 let ind = indent(s)164 let body = s.dropFirst(ind)165 guard let first = body.first, first == "`" || first == "~" else { return nil }166 let count = body.prefix { $0 == first }.count167 guard count >= 3 else { return nil }168 let info = body.dropFirst(count).trimmingCharacters(in: .whitespaces)169 if first == "`", info.contains("`") { return nil }170 return (first, count, info, ind)171 }172173 private static func heading(_ s: String) -> (level: Int, text: String)? {174 let body = s.drop { $0 == " " }175 let level = body.prefix { $0 == "#" }.count176 guard (1 ... 6).contains(level) else { return nil }177 let rest = body.dropFirst(level)178 guard rest.isEmpty || rest.first == " " else { return nil }179 var text = rest.trimmingCharacters(in: .whitespaces)180 // Closing hashes ("## Title ##").181 if let r = text.range(of: #"\s+#+$"#, options: .regularExpression) { text.removeSubrange(r) }182 return (level, text)183 }184185 private static func isRule(_ s: String) -> Bool {186 let compact = s.filter { $0 != " " }187 guard compact.count >= 3, let first = compact.first, first == "-" || first == "*" || first == "_" else { return false }188 return compact.allSatisfy { $0 == first }189 }190191 private static func listMarker(_ s: String) -> (indent: Int, ordered: Bool, marker: String, contentIndent: Int)? {192 let ind = indent(s)193 let body = s.dropFirst(ind)194 guard let first = body.first else { return nil }195 if first == "-" || first == "*" || first == "+" {196 let rest = body.dropFirst()197 guard rest.isEmpty || rest.first == " " else { return nil }198 let spaces = max(1, min(4, rest.prefix { $0 == " " }.count))199 return (ind, false, String(first), ind + 1 + spaces)200 }201 let digits = body.prefix { $0.isASCII && $0.isNumber }202 guard !digits.isEmpty, digits.count <= 9 else { return nil }203 let rest = body.dropFirst(digits.count)204 guard let delimiter = rest.first, delimiter == "." || delimiter == ")" else { return nil }205 let after = rest.dropFirst()206 guard after.isEmpty || after.first == " " else { return nil }207 let spaces = max(1, min(4, after.prefix { $0 == " " }.count))208 return (ind, true, String(digits) + ".", ind + digits.count + 1 + spaces)209 }210211 private static func isQuote(_ s: String) -> Bool { s.drop { $0 == " " }.first == ">" }212213 /// Splits a table row on unescaped pipes outside code spans.214 static func cells(_ s: String) -> [String] {215 var out: [String] = []; var current = ""; var inCode = false; var escaped = false216 for c in s.trimmingCharacters(in: .whitespaces) {217 if escaped { if c != "|" { current.append("\\") }; current.append(c); escaped = false; continue }218 if c == "\\" { escaped = true; continue }219 if c == "`" { inCode.toggle(); current.append(c); continue }220 if c == "|", !inCode { out.append(current); current = ""; continue }221 current.append(c)222 }223 if escaped { current.append("\\") }224 out.append(current)225 if out.first?.trimmingCharacters(in: .whitespaces).isEmpty == true { out.removeFirst() }226 if out.last?.trimmingCharacters(in: .whitespaces).isEmpty == true { out.removeLast() }227 return out.map { $0.trimmingCharacters(in: .whitespaces) }228 }229230 private static func tableAlignments(_ s: String) -> [MDAlignment]? {231 guard s.contains("-") else { return nil }232 let parts = cells(s)233 guard !parts.isEmpty else { return nil }234 var out: [MDAlignment] = []235 for p in parts {236 let core = p.trimmingCharacters(in: CharacterSet(charactersIn: ":"))237 guard !core.isEmpty, core.allSatisfy({ $0 == "-" }) else { return nil }238 out.append(p.hasPrefix(":") && p.hasSuffix(":") ? .center : (p.hasSuffix(":") ? .trailing : .leading))239 }240 return out241 }242243 private static func startsBlock(_ s: String) -> Bool {244 fence(s) != nil || heading(s) != nil || isRule(s) || isQuote(s) || listMarker(s) != nil245 }246247 // MARK: Blocks248249 private mutating func blocks(_ lines: [Line]) -> [MDNode] {250 // Deeply nested quotes or lists in hostile input are flattened instead of recursing without bound.251 guard depth < 12 else {252 let text = lines.map(\.text).joined(separator: " ").trimmingCharacters(in: .whitespaces)253 guard let first = lines.first, !text.isEmpty else { return [] }254 return [MDNode(id: makeID(), line: first.number, lastLine: lines.last?.number ?? first.number, block: .paragraph([.text(text)]))]255 }256 depth += 1; defer { depth -= 1 }257 var out: [MDNode] = []258 var i = 0259 while i < lines.count {260 let line = lines[i]261 if Self.isBlank(line.text) { i += 1; continue }262263 if let f = Self.fence(line.text) {264 var body: [String] = []265 var j = i + 1266 var closed = false267 while j < lines.count {268 if let c = Self.fence(lines[j].text), c.marker == f.marker, c.count >= f.count, c.info.isEmpty { closed = true; break }269 let t = lines[j].text270 body.append(String(t.dropFirst(min(f.indent, Self.indent(t)))))271 j += 1272 }273 let language = f.info.split(separator: " ").first.map { String($0).lowercased() } ?? ""274 out.append(MDNode(id: makeID(), line: line.number, lastLine: lines[min(j, lines.count - 1)].number, block: .code(language: language, text: body.joined(separator: "\n"))))275 i = closed ? j + 1 : j276 continue277 }278279 if let h = Self.heading(line.text) {280 let inl = Self.inlines(h.text)281 out.append(MDNode(id: makeID(), line: line.number, lastLine: line.number, block: .heading(level: min(h.level, 4), text: inl, anchor: uniqueAnchor(inl.map(\.plain).joined()))))282 i += 1; continue283 }284285 if Self.isRule(line.text) {286 out.append(MDNode(id: makeID(), line: line.number, lastLine: line.number, block: .rule))287 i += 1; continue288 }289290 if Self.isQuote(line.text) {291 var inner: [Line] = []292 var j = i293 while j < lines.count, Self.isQuote(lines[j].text) {294 var t = lines[j].text.drop { $0 == " " }.dropFirst()295 if t.first == " " { t = t.dropFirst() }296 inner.append(Line(text: String(t), number: lines[j].number))297 j += 1298 }299 out.append(MDNode(id: makeID(), line: line.number, lastLine: lines[j - 1].number, block: .quote(blocks(inner))))300 i = j; continue301 }302303 if line.text.contains("|"), i + 1 < lines.count, let alignments = Self.tableAlignments(lines[i + 1].text) {304 let header = Self.cells(line.text)305 if !header.isEmpty {306 var rows: [[[MDInline]]] = []307 var j = i + 2308 while j < lines.count, !Self.isBlank(lines[j].text), lines[j].text.contains("|") {309 var row = Self.cells(lines[j].text)310 if row.count < header.count { row += [String](repeating: "", count: header.count - row.count) }311 if row.count > header.count { row = Array(row.prefix(header.count - 1)) + [row[(header.count - 1)...].joined(separator: " | ")] }312 rows.append(row.map(Self.inlines))313 j += 1314 }315 var aligns = alignments316 if aligns.count < header.count { aligns += [MDAlignment](repeating: .leading, count: header.count - aligns.count) }317 out.append(MDNode(id: makeID(), line: line.number, lastLine: lines[j - 1].number,318 block: .table(header: header.map(Self.inlines), alignments: Array(aligns.prefix(header.count)), rows: rows)))319 i = j; continue320 }321 }322323 if let first = Self.listMarker(line.text) {324 var items: [MDListItem] = []325 var j = i326 var last = line.number327 while j < lines.count, let m = Self.listMarker(lines[j].text), m.ordered == first.ordered, m.indent <= first.indent + 1, m.indent >= max(0, first.indent - 1), !Self.isRule(lines[j].text) {328 var inner: [Line] = [Line(text: String(lines[j].text.dropFirst(min(m.contentIndent, lines[j].text.count))), number: lines[j].number)]329 var k = j + 1330 while k < lines.count {331 let t = lines[k].text332 if Self.isBlank(t) {333 // A blank line stays in the item only when indented content follows.334 var n = k + 1335 while n < lines.count, Self.isBlank(lines[n].text) { n += 1 }336 if n < lines.count, Self.indent(lines[n].text) >= min(m.contentIndent, m.indent + 2) { inner.append(Line(text: "", number: lines[k].number)); k += 1; continue }337 break338 }339 let ind = Self.indent(t)340 if ind >= min(m.contentIndent, m.indent + 2) { inner.append(Line(text: String(t.dropFirst(min(m.contentIndent, ind))), number: lines[k].number)); k += 1; continue }341 // Lazy continuation of a paragraph.342 if !Self.startsBlock(t), let previous = inner.last, !Self.isBlank(previous.text) { inner.append(Line(text: t.trimmingCharacters(in: .whitespaces), number: lines[k].number)); k += 1; continue }343 break344 }345 last = lines[k - 1].number346 items.append(MDListItem(marker: m.marker, nodes: blocks(inner)))347 j = k348 // Blank lines between items of the same list.349 var n = j350 while n < lines.count, Self.isBlank(lines[n].text) { n += 1 }351 if n < lines.count, n > j, let next = Self.listMarker(lines[n].text), next.ordered == first.ordered, next.indent == m.indent { j = n }352 }353 if items.isEmpty { // Cannot happen (the first line is a marker), but never loop forever.354 out.append(MDNode(id: makeID(), line: line.number, lastLine: line.number, block: .paragraph(Self.inlines(line.text))))355 i += 1; continue356 }357 out.append(MDNode(id: makeID(), line: line.number, lastLine: last, block: .list(ordered: first.ordered, items: items)))358 i = j; continue359 }360361 // Paragraph.362 var parts: [String] = []363 var j = i364 while j < lines.count, !Self.isBlank(lines[j].text) {365 if j > i, Self.startsBlock(lines[j].text) { break }366 if j > i, lines[j].text.contains("|"), j + 1 < lines.count, Self.tableAlignments(lines[j + 1].text) != nil { break }367 parts.append(lines[j].text)368 j += 1369 }370 var text = ""371 for (n, p) in parts.enumerated() {372 let hard = p.hasSuffix(" ") || p.hasSuffix("\\")373 var t = p.trimmingCharacters(in: .whitespaces)374 if hard, t.hasSuffix("\\") { t.removeLast() }375 text += t376 if n < parts.count - 1 { text += hard ? "\u{2028}" : " " }377 }378 out.append(MDNode(id: makeID(), line: line.number, lastLine: lines[j - 1].number, block: .paragraph(Self.inlines(text))))379 i = max(j, i + 1)380 }381 return out382 }383384 // MARK: Inlines385386 static func inlines(_ source: String) -> [MDInline] {387 var parser = InlineParser(Array(source))388 return parser.parse(until: nil, depth: 0)389 }390391 private struct InlineParser {392 let chars: [Character]393 var i = 0394 init(_ chars: [Character]) { self.chars = chars }395396 private func isWord(_ c: Character?) -> Bool { c.map { $0.isLetter || $0.isNumber } ?? false }397398 /// Position of the closing delimiter run, skipping code spans.399 private func find(_ delimiter: [Character], from start: Int, limit: Int) -> Int? {400 var k = start401 while k + delimiter.count <= limit {402 if chars[k] == "\\" { k += 2; continue }403 if chars[k] == "`" {404 let run = runLength("`", at: k)405 if let close = closingBackticks(run, from: k + run, limit: limit) { k = close + run; continue }406 k += run; continue407 }408 if Array(chars[k ..< k + delimiter.count]) == delimiter {409 let before: Character? = k > 0 ? chars[k - 1] : nil410 let after: Character? = k + delimiter.count < chars.count ? chars[k + delimiter.count] : nil411 let ok = before.map { !$0.isWhitespace } ?? false412 let underscoreOK = delimiter[0] != "_" || !isWord(after)413 // A single delimiter must not be half of a double one.414 let single = delimiter.count == 1 && (after == delimiter[0])415 if ok, underscoreOK, !single { return k }416 if single { k += 2; continue }417 }418 k += 1419 }420 return nil421 }422423 private func runLength(_ c: Character, at k: Int) -> Int { var n = 0; while k + n < chars.count, chars[k + n] == c { n += 1 }; return n }424425 private func closingBackticks(_ run: Int, from start: Int, limit: Int) -> Int? {426 var k = start427 while k < limit {428 if chars[k] == "`" { let n = runLength("`", at: k); if n == run { return k }; k += n } else { k += 1 }429 }430 return nil431 }432433 mutating func parse(until end: Int?, depth: Int) -> [MDInline] {434 let limit = end ?? chars.count435 var out: [MDInline] = []436 var text = ""437 func flush(_ out: inout [MDInline], _ text: inout String) { if !text.isEmpty { out.append(.text(text)); text = "" } }438 while i < limit {439 let c = chars[i]440 if c == "\\", i + 1 < limit, chars[i + 1].isPunctuation || chars[i + 1].isSymbol { text.append(chars[i + 1]); i += 2; continue }441 if c == "\u{2028}" { flush(&out, &text); out.append(.lineBreak); i += 1; continue }442 if c == "`" {443 let run = runLength("`", at: i)444 if let close = closingBackticks(run, from: i + run, limit: limit) {445 flush(&out, &text)446 var code = String(chars[(i + run) ..< close])447 if code.hasPrefix(" "), code.hasSuffix(" "), code.contains(where: { $0 != " " }) { code = String(code.dropFirst().dropLast()) }448 out.append(.code(code))449 i = close + run; continue450 }451 text.append(String(repeating: "`", count: run)); i += run; continue452 }453 if depth < 8, c == "*" || c == "_" {454 let run = min(2, runLength(c, at: i))455 let before: Character? = i > 0 ? chars[i - 1] : nil456 let next: Character? = i + run < limit ? chars[i + run] : nil457 let opens = next.map { !$0.isWhitespace } ?? false458 let underscoreOK = c != "_" || !isWord(before)459 if opens, underscoreOK, let close = find([Character](repeating: c, count: run), from: i + run, limit: limit), close > i + run {460 flush(&out, &text)461 var inner = InlineParser(chars); inner.i = i + run462 let children = inner.parse(until: close, depth: depth + 1)463 out.append(run == 2 ? .strong(children) : .emphasis(children))464 i = close + run; continue465 }466 text.append(String(repeating: String(c), count: run)); i += run; continue467 }468 if depth < 8, c == "[" || (c == "!" && i + 1 < limit && chars[i + 1] == "[") {469 let open = c == "!" ? i + 1 : i470 if let link = link(at: open, limit: limit) {471 flush(&out, &text)472 var inner = InlineParser(chars); inner.i = open + 1473 let children = inner.parse(until: link.labelEnd, depth: depth + 1)474 out.append(c == "!" ? .emphasis(children) : .link(children, link.destination))475 i = link.end; continue476 }477 }478 if c == "<", let close = chars[i ..< limit].firstIndex(of: ">") {479 let inside = String(chars[(i + 1) ..< close])480 if inside.hasPrefix("http://") || inside.hasPrefix("https://") || inside.hasPrefix("mailto:"), !inside.contains(" ") {481 flush(&out, &text); out.append(.link([.text(inside)], inside)); i = close + 1; continue482 }483 }484 text.append(c); i += 1485 }486 flush(&out, &text)487 return out488 }489490 /// `[label](destination "title")` starting at the opening bracket.491 private func link(at open: Int, limit: Int) -> (labelEnd: Int, destination: String, end: Int)? {492 var level = 0; var k = open493 var labelEnd: Int?494 while k < limit {495 if chars[k] == "\\" { k += 2; continue }496 if chars[k] == "`" {497 let run = runLength("`", at: k)498 if let close = closingBackticks(run, from: k + run, limit: limit) { k = close + run; continue }499 k += run; continue500 }501 if chars[k] == "[" { level += 1 } else if chars[k] == "]" { level -= 1; if level == 0 { labelEnd = k; break } }502 k += 1503 }504 guard let labelEnd, labelEnd + 1 < limit, chars[labelEnd + 1] == "(" else { return nil }505 var paren = 0; k = labelEnd + 1506 while k < limit {507 if chars[k] == "(" { paren += 1 } else if chars[k] == ")" { paren -= 1; if paren == 0 { break } }508 k += 1509 }510 guard k < limit, paren == 0 else { return nil }511 var destination = String(chars[(labelEnd + 2) ..< k]).trimmingCharacters(in: .whitespaces)512 if let space = destination.firstIndex(of: " ") { destination = String(destination[..<space]) }513 if destination.hasPrefix("<"), destination.hasSuffix(">") { destination = String(destination.dropFirst().dropLast()) }514 return (labelEnd, destination, k + 1)515 }516 }517}518