SPB Git

Repository Public License

MatrixCommand.swift 24.4 KB 362 lines swift

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
Files main
Menu

Theme