Repository Public License
1// ORIX Convert — Packages/ConvertKit/Sources/ConvertCLI/MatrixCommand.swift2// Description: `orix-convert matrix`: the conversion matrix generated from the live registry (Markdown and JSON),3// enriched with the test names and measured numbers stated in each engine's notes; `--verify` runs the4// cross-engine end-to-end sweep.5// Author: Simon-Pierre Boucher — contact@spboucher.ai6import Foundation7import CryptoKit8import ConvertCore9import ConvertKit1011/// What the engine notes (`docs/compatibility/engines/*.md`) say about each path: covering test, measured number.12struct EngineNotes {13 struct Entry { var test: String?; var performance: String? }14 /// Keyed by `package|source>destination#operation`.15 private(set) var tests: [String: String] = [:]16 /// Keyed by `package|source>destination`.17 private(set) var performance: [String: String] = [:]18 /// Suite used when the notes name no test for a path, per package.19 private(set) var fallbackSuite: [String: String] = [:]20 private(set) var documents: [String: String] = [:]21 /// Test the notes name in a sentence for every plain conversion of a package, and for every path from a format.22 private(set) var packageTest: [String: String] = [:]23 private(set) var sourceTest: [String: String] = [:]2425 static func key(_ package: String, _ source: String, _ destination: String, _ operation: String?) -> String {26 "\(package)|\(source)>\(destination)#\(operation ?? "")"27 }2829 /// The engine package a notes file belongs to (`model3d.md` → `EngineModel3D`).30 static func package(forDocument name: String, packages: [String]) -> String? {31 let base = name.lowercased().replacingOccurrences(of: ".md", with: "").replacingOccurrences(of: "-", with: "").replacingOccurrences(of: "_", with: "")32 let aliases = ["3d": "model3d", "models": "model3d", "model": "model3d", "subtitles": "subtitle", "fonts": "font", "archives": "archive",33 "geospatial": "geo", "images": "image", "document": "documents", "science": "scientific", "audio": "media", "video": "media"]34 let wanted = aliases[base] ?? base35 return packages.first { $0.lowercased().replacingOccurrences(of: "engine", with: "") == wanted }36 }3738 static func load(repository: URL?, packages: [String], enginesByPackage: [String: [String]]) -> EngineNotes {39 var notes = EngineNotes()40 guard let repository else { return notes }41 let fm = FileManager.default42 let folder = repository.appendingPathComponent("docs/compatibility/engines")43 for name in ((try? fm.contentsOfDirectory(atPath: folder.path)) ?? []).sorted() where name.hasSuffix(".md") {44 guard let package = package(forDocument: name, packages: packages),45 let text = try? String(contentsOf: folder.appendingPathComponent(name), encoding: .utf8) else { continue }46 notes.documents[package] = "docs/compatibility/engines/" + name47 notes.parse(text, package: package, engines: enginesByPackage[package] ?? [])48 }49 for package in packages {50 let tests = repository.appendingPathComponent("Packages/\(package)/Tests/\(package)Tests")51 let files = ((try? fm.contentsOfDirectory(atPath: tests.path)) ?? []).filter { $0.hasSuffix(".swift") }.sorted()52 for marker in ["Matrix", "PathTable", "DocTable", "Path"] {53 if let file = files.first(where: { $0.contains(marker) }) {54 notes.fallbackSuite[package] = "\(package)Tests/\(file.replacingOccurrences(of: ".swift", with: "")) (suite)"55 break56 }57 }58 }59 return notes60 }6162 static func cells(_ line: String) -> [String]? {63 let trimmed = line.trimmingCharacters(in: .whitespaces)64 guard trimmed.hasPrefix("|") else { return nil }65 var cells: [String] = []66 var current = ""67 var escaped = false, inCode = false68 for character in trimmed.dropFirst() {69 if escaped { current.append(character); escaped = false; continue }70 if character == "\\" { escaped = true; current.append(character); continue }71 if character == "`" { inCode.toggle() }72 if character == "|" && !inCode { cells.append(current.trimmingCharacters(in: .whitespaces)); current = "" } else { current.append(character) }73 }74 if !current.trimmingCharacters(in: .whitespaces).isEmpty { cells.append(current.trimmingCharacters(in: .whitespaces)) }75 return cells76 }7778 static func plain(_ cell: String) -> String {79 cell.replacingOccurrences(of: "`", with: "").replacingOccurrences(of: "\\|", with: "|").trimmingCharacters(in: .whitespaces)80 }8182 static func formatID(_ cell: String) -> String? {83 let text = plain(cell).lowercased()84 if FormatCatalog.format(FormatID(text)) != nil { return text }85 return nil86 }8788 /// The format identifiers of a source cell: one (`pdf`) or a list (`png, jpeg, heic`).89 static func formatIDs(_ cell: String) -> [String] {90 let parts = plain(cell).split(separator: ",").map { String($0).trimmingCharacters(in: .whitespaces) }91 let ids = parts.compactMap { formatID($0) }92 return ids.count == parts.count ? ids : []93 }9495 /// The operation identifier of an operation cell: the first code span (`` `pdf.merge` (multiple sources) ``), or96 /// the plain text; `nil` for a plain conversion (`—`, `–`, `-`, `convert`, `— (multiple sources)`).97 static func operation(_ cell: String) -> String? {98 let trimmed = cell.trimmingCharacters(in: .whitespaces)99 if let open = trimmed.firstIndex(of: "`"), let close = trimmed[trimmed.index(after: open)...].firstIndex(of: "`") {100 let code = String(trimmed[trimmed.index(after: open)..<close]).trimmingCharacters(in: .whitespaces)101 return code.isEmpty ? nil : code102 }103 let raw = plain(trimmed)104 if let first = raw.first, "—–-".contains(first) { return nil }105 return ["", "convert", "conversion", "none"].contains(raw.lowercased()) ? nil : raw106 }107108 /// The first code span that follows `marker` in a line of prose.109 static func codeSpan(after marker: String, in line: String) -> String? {110 guard let found = line.range(of: marker), let open = line[found.upperBound...].firstIndex(of: "`") else { return nil }111 let rest = line[line.index(after: open)...]112 guard let close = rest.firstIndex(of: "`"), line[found.upperBound..<open].allSatisfy({ $0 == " " }) else { return nil }113 return String(rest[..<close])114 }115116 /// Notes that state the covering test in a sentence instead of a table column:117 /// "Test for all of them: `PathTests.convertsCities(_:)`" names the test of every plain path of the package;118 /// "Test: `KMZSourceTests`" under a heading "KMZ as a source" names the test of every path from that format.119 mutating func parseProse(_ line: String, heading: String, package: String) {120 if let test = Self.codeSpan(after: "Test for all of them:", in: line) ?? Self.codeSpan(after: "Tests for all of them:", in: line) {121 if packageTest[package] == nil { packageTest[package] = test }122 return123 }124 let words = heading.drop(while: { $0 == "#" || $0 == " " }).split(separator: " ").map(String.init)125 guard words.count >= 4, words[1...3].map({ $0.lowercased() }) == ["as", "a", "source"], let source = Self.formatID(words[0]),126 let test = Self.codeSpan(after: "Test:", in: line) else { return }127 if sourceTest["\(package)|\(source)"] == nil { sourceTest["\(package)|\(source)"] = test }128 }129130 /// Resolves a human label (`JSON Lines`, `PNG`, `Arrow IPC file`) to a format identifier.131 static func resolveName(_ words: [String]) -> String? {132 let label = words.joined(separator: " ").lowercased()133 if FormatCatalog.format(FormatID(label)) != nil { return label }134 if let match = FormatCatalog.all.first(where: { $0.name.lowercased() == label }) { return match.id.rawValue }135 if words.count == 1, let match = FormatCatalog.formats(forExtension: label).first { return match.id.rawValue }136 return nil137 }138139 mutating func parse(_ text: String, package: String, engines: [String]) {140 var heading = ""141 var header: [String]?142 for line in text.components(separatedBy: "\n") {143 if line.hasPrefix("#") { heading = line; header = nil; continue }144 guard let cells = Self.cells(line) else {145 header = nil146 parseProse(line, heading: heading, package: package)147 continue148 }149 if cells.allSatisfy({ $0.allSatisfy { "-: ".contains($0) } }) { continue }150 guard let columns = header else { header = cells.map { Self.plain($0).lowercased() }; continue }151 if let s = columns.firstIndex(of: "source"), let d = columns.firstIndex(of: "destination"), s < cells.count, d < cells.count,152 let destination = Self.formatID(cells[d]), case let sources = Self.formatIDs(cells[s]), !sources.isEmpty {153 let operation = columns.firstIndex(of: "operation").flatMap { $0 < cells.count ? Self.operation(cells[$0]) : nil }154 if let t = columns.firstIndex(where: { $0.hasPrefix("test") }), t < cells.count {155 let test = Self.plain(cells[t])156 if !test.isEmpty, test != "—" {157 for source in sources {158 let key = Self.key(package, source, destination, operation)159 if tests[key] == nil { tests[key] = test }160 }161 }162 }163 } else if heading.lowercased().contains("performance"), cells.count >= 2 {164 // A measured row such as "PNG → JPEG (q 85) | 18 | on | 9.76 s | …".165 let label = Self.plain(cells[0])166 guard let arrow = label.range(of: "→") ?? label.range(of: "->") else { continue }167 var left = String(label[..<arrow.lowerBound])168 if let paren = left.range(of: "(") { left = String(left[..<paren.lowerBound]) }169 let leftWords = left.split(whereSeparator: { " ,".contains($0) }).map(String.init)170 let rightWords = label[arrow.upperBound...].split(whereSeparator: { " ,(".contains($0) }).map(String.init)171 var source: String?, destination: String?172 for count in stride(from: min(3, leftWords.count), to: 0, by: -1) where source == nil { source = Self.resolveName(Array(leftWords.suffix(count))) }173 for count in stride(from: min(3, rightWords.count), to: 0, by: -1) where destination == nil { destination = Self.resolveName(Array(rightWords.prefix(count))) }174 guard let source, let destination else { continue }175 let index = columns.firstIndex(where: { $0.contains("time") || $0.contains("wall") || $0.hasPrefix("run") }) ?? 1176 guard index < cells.count, index < columns.count else { continue }177 let value = Self.plain(cells[index])178 guard value.contains(where: \.isNumber) else { continue }179 let key = "\(package)|\(source)>\(destination)"180 if performance[key] == nil { performance[key] = "\(value) (\(columns[index]); \(label))" }181 }182 }183 }184185 func test(package: String, path: ConversionPath) -> String? {186 tests[Self.key(package, path.source.rawValue, path.destination.rawValue, path.operation)]187 ?? sourceTest["\(package)|\(path.source.rawValue)"]188 ?? (path.operation == nil ? packageTest[package] : nil)189 }190191 func performance(package: String, path: ConversionPath) -> String? {192 path.operation == nil ? performance["\(package)|\(path.source.rawValue)>\(path.destination.rawValue)"] : nil193 }194}195196struct MatrixDocument: Codable {197 struct Row: Codable {198 let source: String, destination: String, operation: String?, title: String?, engine: String, package: String199 let category: String200 let status: String, fidelity: String201 let preserves: [String], limitations: [String]202 let acceptsMultipleSources: Bool203 let test: String?204 /// `notes` when the engine notes name the test, `suite` when only the engine's matrix suite is known.205 let testSource: String?206 let performance: String?207 let unavailableReason: String?208 }209210 struct Totals: Codable {211 let formatsWithPath: Int, sourceFormats: Int, destinationFormats: Int212 let distinctPairs: Int, pairsWithSupportedPath: Int, conversionPairs: Int213 let paths: Int, plainConversionPaths: Int, operationPaths: Int, namedOperations: Int214 let unavailablePaths: Int215 let byEngine: [String: Int], byStatus: [String: Int], byFidelity: [String: Int], byCategory: [String: Int]216 let testsFromNotes: Int, testsFromSuite: Int, testsUnknown: Int, pathsWithMeasuredPerformance: Int217 }218219 struct Identity: Codable {220 let tool: String221 let wiredPackages: [String], notWiredPackages: [String]222 let engines: [String]223 /// SHA-256 of the sorted path identifiers with their status and fidelity: changes exactly when the matrix does.224 let registryFingerprint: String225 }226227 let identity: Identity228 let totals: Totals229 let rows: [Row]230}231232enum MatrixBuilder {233 static func build(registry: FormatRegistry, repository: URL?) -> MatrixDocument {234 var packageOf: [String: String] = [:]235 var enginesByPackage: [String: [String]] = [:]236 for entry in ORIXEngines.byPackage() {237 for engine in entry.engines { packageOf[engine.id] = entry.package; enginesByPackage[entry.package, default: []].append(engine.id) }238 }239 let notes = EngineNotes.load(repository: repository, packages: ORIXEngines.wiredPackages, enginesByPackage: enginesByPackage)240 func row(_ path: ConversionPath, reason: String?) -> MatrixDocument.Row {241 let package = packageOf[path.engine] ?? "?"242 var test = notes.test(package: package, path: path)243 var testSource: String? = test == nil ? nil : "notes"244 if test == nil, let suite = notes.fallbackSuite[package] { test = suite; testSource = "suite" }245 return MatrixDocument.Row(246 source: path.source.rawValue, destination: path.destination.rawValue, operation: path.operation, title: path.title, engine: path.engine,247 package: package, category: (FormatCatalog.format(path.source)?.category ?? .other).rawValue,248 status: reason == nil ? path.status.rawValue : "unavailable", fidelity: path.fidelity.rawValue,249 preserves: path.preserves.map(\.rawValue).sorted(), limitations: path.limitations, acceptsMultipleSources: path.acceptsMultipleSources,250 test: test, testSource: testSource, performance: notes.performance(package: package, path: path), unavailableReason: reason)251 }252 var rows = registry.paths.map { row($0, reason: nil) }253 for engine in registry.unavailableEngines { rows += engine.paths.map { row($0, reason: engine.reason) } }254 let available = rows.filter { $0.unavailableReason == nil }255 func count(_ key: (MatrixDocument.Row) -> String, in list: [MatrixDocument.Row]) -> [String: Int] {256 Dictionary(grouping: list, by: key).mapValues(\.count)257 }258 let c = registry.counts259 let totals = MatrixDocument.Totals(260 formatsWithPath: c.formatsWithPath, sourceFormats: c.sourceFormats, destinationFormats: c.destinationFormats,261 distinctPairs: c.distinctPairs, pairsWithSupportedPath: c.verifiedPairs, conversionPairs: c.conversionPairs,262 paths: c.availablePaths, plainConversionPaths: available.filter { $0.operation == nil }.count,263 operationPaths: available.filter { $0.operation != nil }.count, namedOperations: c.operations, unavailablePaths: c.unavailablePaths,264 byEngine: count(\.engine, in: available), byStatus: count(\.status, in: rows), byFidelity: count(\.fidelity, in: available),265 byCategory: count(\.category, in: available),266 testsFromNotes: available.filter { $0.testSource == "notes" }.count, testsFromSuite: available.filter { $0.testSource == "suite" }.count,267 testsUnknown: available.filter { $0.test == nil }.count, pathsWithMeasuredPerformance: available.filter { $0.performance != nil }.count)268 let fingerprintInput = rows.map { "\($0.engine):\($0.source)>\($0.destination)#\($0.operation ?? "")|\($0.status)|\($0.fidelity)" }.sorted().joined(separator: "\n")269 let fingerprint = SHA256.hash(data: Data(fingerprintInput.utf8)).map { String(format: "%02x", $0) }.joined()270 let identity = MatrixDocument.Identity(tool: "orix-convert \(CLI.version)", wiredPackages: ORIXEngines.wiredPackages,271 notWiredPackages: ORIXEngines.knownPackages.filter { !ORIXEngines.wiredPackages.contains($0) },272 engines: registry.engines.map(\.id), registryFingerprint: fingerprint)273 return MatrixDocument(identity: identity, totals: totals, rows: rows)274 }275276 static func markdown(_ document: MatrixDocument) -> String {277 func cell(_ text: String) -> String { text.replacingOccurrences(of: "|", with: "\\|").replacingOccurrences(of: "\n", with: " ") }278 let t = document.totals279 var out = "# ORIX Convert — conversion matrix\n\n"280 out += "> Generated file — do not edit. Produced by `Scripts/matrix.sh` (`orix-convert matrix --markdown`) from the live engine\n"281 out += "> registry of the build: every row is a `ConversionPath` an engine declares, and every total below is computed from those\n"282 out += "> rows. The Tests and Performance columns are read from the engine notes in `docs/compatibility/engines/`.\n"283 out += "> The end-to-end result of each path is in `docs/reports/e2e-matrix.md`.\n\n"284 out += "Build identity (no date, no commit: the fingerprint changes exactly when the matrix changes):\n\n"285 out += "- Tool: `\(document.identity.tool)`\n"286 out += "- Engine packages in the build (\(document.identity.wiredPackages.count)): \(document.identity.wiredPackages.joined(separator: ", "))\n"287 if !document.identity.notWiredPackages.isEmpty { out += "- Engine packages not in the build: \(document.identity.notWiredPackages.joined(separator: ", "))\n" }288 out += "- Engines (\(document.identity.engines.count)): \(document.identity.engines.map { "`\($0)`" }.joined(separator: ", "))\n"289 out += "- Registry fingerprint (SHA-256): `\(document.identity.registryFingerprint)`\n\n"290 out += "## Totals\n\n| Measure | Count |\n|---|---:|\n"291 out += "| Formats with at least one path | \(t.formatsWithPath) |\n| …readable (source of a path) | \(t.sourceFormats) |\n| …writable (destination of a path) | \(t.destinationFormats) |\n"292 out += "| Distinct source → destination pairs | \(t.distinctPairs) |\n| …of which with a `supported` path | \(t.pairsWithSupportedPath) |\n| …of which reachable by a plain conversion | \(t.conversionPairs) |\n"293 out += "| Paths (conversions and operations) | \(t.paths) |\n| …plain conversions | \(t.plainConversionPaths) |\n| …operation paths | \(t.operationPaths) |\n| Named operations | \(t.namedOperations) |\n"294 out += "| Paths of unavailable engines | \(t.unavailablePaths) |\n\n"295 func table(_ title: String, _ counts: [String: Int], order: [String]? = nil) -> String {296 var text = "| \(title) | Paths |\n|---|---:|\n"297 let keys = order?.filter { counts[$0] != nil } ?? counts.keys.sorted()298 for key in keys { text += "| \(key) | \(counts[key] ?? 0) |\n" }299 return text + "\n"300 }301 out += table("Engine", t.byEngine, order: document.identity.engines)302 out += table("Status", t.byStatus)303 out += table("Fidelity", t.byFidelity)304 out += table("Source category", t.byCategory, order: FormatCategory.allCases.map(\.rawValue))305 out += "Tests column: \(t.testsFromNotes) path(s) carry the test named in the engine notes, \(t.testsFromSuite) the engine's matrix suite "306 out += "(the notes name no test for them), \(t.testsUnknown) none. Performance column: \(t.pathsWithMeasuredPerformance) path(s) have a number "307 out += "measured by the engine's author and quoted from the notes with its scenario; \"—\" means no measurement exists for that path.\n\n"308 for category in FormatCategory.allCases {309 let rows = document.rows.filter { $0.category == category.rawValue }310 guard !rows.isEmpty else { continue }311 out += "## \(category.rawValue) sources (\(rows.count) paths)\n\n"312 out += "| Source | Destination | Operation | Engine | Status | Fidelity | Preserves | Limitations | Tests | Performance |\n|---|---|---|---|---|---|---|---|---|---|\n"313 for row in rows {314 var limitations = row.limitations315 if let reason = row.unavailableReason { limitations.insert("Unavailable: \(reason)", at: 0) }316 let cells = [row.source, row.destination, row.operation.map { "`\($0)`" } ?? "—", row.engine, row.status, row.fidelity,317 row.preserves.isEmpty ? "—" : row.preserves.joined(separator: ", "), limitations.isEmpty ? "—" : limitations.joined(separator: " "),318 row.test ?? "—", row.performance ?? "—"]319 out += "| " + cells.map(cell).joined(separator: " | ") + " |\n"320 }321 out += "\n"322 }323 return out324 }325}326327enum MatrixCommand: Command {328 static let spec = CommandSpec(329 "matrix", summary: "Generate the conversion matrix; --verify runs every path end to end.",330 usage: "matrix --markdown | --json [--output <file>]\n orix-convert matrix --verify [--report-dir <dir>] [--work-dir <dir>] [--jobs <n>] [--heavy-jobs <n>] [--timeout <seconds>] [--engine <id>] [--from <format>] [--to <format>] [--chains <n>] [--fresh] [--retry-failed] [--keep-outputs]",331 flags: ["markdown", "json", "verify", "fresh", "retry-failed", "keep-outputs", "no-chains"],332 options: ["output", "report-dir", "work-dir", "jobs", "heavy-jobs", "timeout", "engine", "from", "to", "chains", "repository", "only-id"],333 details: [334 " --markdown / --json print the matrix (or write it to --output)",335 " --verify for every declared path: obtain a real fixture of the source format (seeds generated in",336 " code, the rest converted through the engines), then run detector → planner → queue →",337 " engine → validation → safe writer, and record pass / fail / skip with timing",338 " --report-dir <dir> where e2e-matrix.md and e2e-matrix.json are written (default: docs/reports in the repository)",339 " --work-dir <dir> fixtures and resumable state (default: $TMPDIR/orix-convert-e2e)",340 " --timeout <seconds> per path, counted from the moment its job starts (default 300)",341 " --chains <n> sample size of chained (two-step) plans to run (default 40)",342 " --fresh forget the saved state and fixtures; --retry-failed re-runs only what did not pass",343 ])344345 static func run(_ arguments: ParsedArguments, io: CommandIO) async throws -> ExitCode {346 let repository = arguments.value("repository").map(Shared.fileURL) ?? Repository.root()347 if arguments.flag("verify") { return try await Sweep.run(arguments, io: io, repository: repository) }348 guard arguments.flag("markdown") != arguments.flag("json") else { throw UsageError("matrix needs --markdown, --json or --verify.") }349 let document = MatrixBuilder.build(registry: Shared.registry(), repository: repository)350 let text = arguments.flag("json") ? try Shared.json(document) : MatrixBuilder.markdown(document)351 if let output = arguments.value("output") {352 let url = Shared.fileURL(output)353 try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)354 try Data((text.hasSuffix("\n") ? text : text + "\n").utf8).write(to: url, options: .atomic)355 io.err("Wrote \(url.path) (\(document.totals.paths) paths).")356 } else {357 io.out(text)358 }359 return .success360 }361}362