Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/orixdocs/main.swift3// Description: The orixdocs command-line tool: convert, audit, stats, compare, workflow run/list, formats. Headless; no dependency.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import DocModel9import DocContainer10import DocAutomation11import DocReview12import DocAudit1314// MARK: Exit codes1516enum Exit: Int32 {17 case ok = 018 /// The operation failed (unreadable input, conversion error, I/O error).19 case failure = 120 /// Bad command line.21 case usage = 222 /// An output file exists and --force was not given.23 case outputExists = 324 /// A batch finished, but at least one input failed.25 case partialFailure = 426 /// `audit --fail-on-error` found at least one error.27 case auditErrors = 528 /// Interrupted (Ctrl-C) before the work was finished.29 case cancelled = 13030}3132struct CLIError: Error {33 var code: Exit34 var message: String35}3637func out(_ s: String) { FileHandle.standardOutput.write(Data((s.hasSuffix("\n") ? s : s + "\n").utf8)) }38func err(_ s: String) { FileHandle.standardError.write(Data(("orixdocs: " + s + "\n").utf8)) }3940// MARK: Help4142enum Help {43 static let main = """44 orixdocs \(AutomationReports.toolVersion) — ORIX Docs from the command line4546 USAGE47 orixdocs convert <input> <output> [--theme <name>] [--paper <size>] [--accept-changes] [--force]48 orixdocs audit <input> [--profile standard|academic|business|minimal] [--json] [--fail-on-error]49 orixdocs stats <input> [--json]50 orixdocs compare <original> <revised> [--report <out.md>] [--merged <out.orixdoc>] [--force]51 orixdocs workflow run <workflow.json|builtin-name> <inputs…> --out <dir> [--jobs <n>] [--force]52 orixdocs workflow list [--json]53 orixdocs formats54 orixdocs --version55 orixdocs <command> --help5657 EXIT CODES58 0 success59 1 the operation failed (unreadable input, conversion or I/O error)60 2 bad command line61 3 an output file already exists and --force was not given62 4 a batch finished but at least one input failed63 5 audit --fail-on-error found at least one error64 130 interrupted6566 Results go to standard output, errors and progress to standard error.67 An existing file is never overwritten without --force. Nothing is sent over the network.68 """6970 static let convert = """71 orixdocs convert <input> <output> [options]7273 Converts a document. The formats are taken from the file extensions (see `orixdocs formats`).7475 OPTIONS76 --theme <name> Apply a theme before writing: \(Theme.all.map(\.name).joined(separator: ", "))77 --paper <size> Set the paper of every section: a4, letter, legal, a5, b5, tabloid, trade78 --accept-changes Accept every tracked change before writing79 --force Replace <output> if it exists8081 Warnings about what the target format cannot carry are printed on standard error.82 """8384 static let audit = """85 orixdocs audit <input> [options]8687 Audits a document: structure, cross-references, captions, bibliography, review leftovers, layout.8889 OPTIONS90 --profile <name> standard (default), academic, business or minimal91 --json Print the findings as JSON92 --fail-on-error Exit with code 5 when a finding has severity "error"93 """9495 static let stats = """96 orixdocs stats <input> [--json]9798 Prints page, word, character, paragraph and object counts, and the estimated reading time.99 """100101 static let compare = """102 orixdocs compare <original> <revised> [options]103104 Compares two documents and prints a summary of the differences.105106 OPTIONS107 --report <out.md> Write the full comparison report (Markdown)108 --merged <out.orixdoc> Write the merged document, differences as tracked changes (any export format)109 --force Replace existing output files110 """111112 static let workflow = """113 orixdocs workflow run <workflow.json|builtin-name> <inputs…> --out <dir> [--jobs <n>] [--force] [--quiet]114 orixdocs workflow list [--json]115116 Runs a workflow on one or many documents. A failing input does not stop the others.117118 OPTIONS119 --out <dir> Output folder (required; created if needed). Workflows cannot write outside it.120 --jobs <n> Documents processed at the same time (default: number of cores, at most 8)121 --force Replace existing output files122 --quiet No per-file progress or warnings on standard error123124 Built-in workflows: \(BuiltinWorkflows.all.map(\.id).joined(separator: ", "))125 The JSON format is described in docs/development/automation.md.126 """127}128129// MARK: Argument parsing130131/// Splits arguments into positionals, flags and valued options, refusing anything not declared.132struct Arguments {133 var positionals: [String] = []134 var flags: Set<String> = []135 var values: [String: String] = [:]136 var wantsHelp = false137138 init(_ args: [String], flags allowedFlags: Set<String>, options allowedOptions: Set<String>) throws {139 var i = 0140 var literal = false141 while i < args.count {142 let a = args[i]143 i += 1144 if literal || !a.hasPrefix("-") || a == "-" { positionals.append(a); continue }145 if a == "--" { literal = true; continue }146 if a == "--help" || a == "-h" { wantsHelp = true; continue }147 var name = a148 var inlineValue: String?149 if let eq = a.firstIndex(of: "="), a.hasPrefix("--") { name = String(a[..<eq]); inlineValue = String(a[a.index(after: eq)...]) }150 if allowedFlags.contains(name) {151 guard inlineValue == nil else { throw CLIError(code: .usage, message: "option \(name) takes no value") }152 flags.insert(name)153 } else if allowedOptions.contains(name) {154 if let v = inlineValue { values[name] = v }155 else if i < args.count { values[name] = args[i]; i += 1 }156 else { throw CLIError(code: .usage, message: "option \(name) needs a value") }157 } else {158 throw CLIError(code: .usage, message: "unknown option \(a)")159 }160 }161 }162163 func expect(_ n: Int, _ usage: String) throws {164 guard positionals.count == n else {165 throw CLIError(code: .usage, message: positionals.count < n ? "missing argument. Usage: \(usage)" : "unexpected argument “\(positionals[n])”. Usage: \(usage)")166 }167 }168}169170func fileURL(_ path: String) -> URL { URL(fileURLWithPath: (path as NSString).expandingTildeInPath).standardizedFileURL }171172func readDocument(_ path: String) throws -> ImportResult {173 let url = fileURL(path)174 guard FileManager.default.fileExists(atPath: url.path) else { throw CLIError(code: .failure, message: "\(path): no such file") }175 guard DocFormat(fileExtension: url.pathExtension) != nil else {176 throw CLIError(code: .failure, message: "\(path): unknown file type “.\(url.pathExtension)” (see `orixdocs formats`)")177 }178 do { return try DocumentConverter.importDocument(at: url) }179 catch { throw CLIError(code: .failure, message: "\(path): \(error)") }180}181182func checkWritable(_ url: URL, force: Bool) throws {183 if FileManager.default.fileExists(atPath: url.path), !force {184 throw CLIError(code: .outputExists, message: "\(url.path) already exists (use --force to replace it)")185 }186}187188func printWarnings(_ warnings: [FormatWarning], prefix: String) {189 for w in warnings {190 FileHandle.standardError.write(Data("\(prefix): \(w.severity.rawValue): \(w.feature) — \(w.detail)\(w.count > 1 ? " (×\(w.count))" : "")\n".utf8))191 }192}193194// MARK: Commands195196func convert(_ args: [String]) throws -> Exit {197 let a = try Arguments(args, flags: ["--accept-changes", "--force"], options: ["--theme", "--paper"])198 if a.wantsHelp { out(Help.convert); return .ok }199 try a.expect(2, "orixdocs convert <input> <output>")200 let output = fileURL(a.positionals[1])201 guard let format = DocFormat(fileExtension: output.pathExtension), DocumentConverter.exportFormats.contains(format) else {202 throw CLIError(code: .usage, message: "cannot write “.\(output.pathExtension)” files (see `orixdocs formats`)")203 }204 var theme: Theme?205 if let name = a.values["--theme"] {206 guard let t = Theme.all.first(where: { $0.name.lowercased() == name.lowercased() }) else {207 throw CLIError(code: .usage, message: "unknown theme “\(name)”. Themes: \(Theme.all.map(\.name).joined(separator: ", "))")208 }209 theme = t210 }211 var paper: PaperSize?212 if let name = a.values["--paper"] {213 guard let p = PageSetupOptions.paperSize(named: name) else { throw CLIError(code: .usage, message: "unknown paper “\(name)”. Papers: a4, letter, legal, a5, b5, tabloid, trade") }214 paper = p215 }216 try checkWritable(output, force: a.flags.contains("--force"))217 let imported = try readDocument(a.positionals[0])218 printWarnings(imported.warnings, prefix: "import")219 var doc = imported.document220 if a.flags.contains("--accept-changes") { doc.resolveChanges(accept: true) }221 if let theme { doc.styles.applyTheme(theme) }222 if let paper {223 for s in 0..<doc.sectionSetups.count { var setup = doc.setup(ofSection: s); setup.paper = paper; doc.setSetup(setup, ofSection: s) }224 }225 do {226 let result = try DocumentConverter.export(doc, format: format)227 try result.data.write(to: output, options: .atomic)228 printWarnings(result.warnings, prefix: "export")229 } catch { throw CLIError(code: .failure, message: "\(output.path): \(error)") }230 out(output.path)231 return .ok232}233234func audit(_ args: [String]) throws -> Exit {235 let a = try Arguments(args, flags: ["--json", "--fail-on-error"], options: ["--profile"])236 if a.wantsHelp { out(Help.audit); return .ok }237 try a.expect(1, "orixdocs audit <input>")238 let name = a.values["--profile"] ?? "standard"239 guard let profile = AuditProfile(rawValue: name) else { throw CLIError(code: .usage, message: "unknown profile “\(name)”. Profiles: standard, academic, business, minimal") }240 let doc = try readDocument(a.positionals[0]).document241 let findings = AutomationReports.audit(doc, profile: profile)242 if a.flags.contains("--json") {243 do { out(String(decoding: try AutomationReports.auditJSON(findings, input: fileURL(a.positionals[0]).path, profile: profile), as: UTF8.self)) }244 catch { throw CLIError(code: .failure, message: "\(error)") }245 } else {246 out(AutomationReports.auditText(findings, name: fileURL(a.positionals[0]).lastPathComponent))247 }248 return a.flags.contains("--fail-on-error") && findings.contains { $0.severity == .error } ? .auditErrors : .ok249}250251func stats(_ args: [String]) throws -> Exit {252 let a = try Arguments(args, flags: ["--json"], options: [])253 if a.wantsHelp { out(Help.stats); return .ok }254 try a.expect(1, "orixdocs stats <input>")255 let doc = try readDocument(a.positionals[0]).document256 let s = AutomationReports.statistics(doc)257 if a.flags.contains("--json") {258 do { out(String(decoding: try AutomationReports.statisticsJSON(s, input: fileURL(a.positionals[0]).path), as: UTF8.self)) }259 catch { throw CLIError(code: .failure, message: "\(error)") }260 } else {261 out(AutomationReports.statisticsText(s, name: fileURL(a.positionals[0]).lastPathComponent))262 }263 return .ok264}265266func compare(_ args: [String]) throws -> Exit {267 let a = try Arguments(args, flags: ["--force"], options: ["--report", "--merged"])268 if a.wantsHelp { out(Help.compare); return .ok }269 try a.expect(2, "orixdocs compare <original> <revised>")270 let force = a.flags.contains("--force")271 let reportURL = a.values["--report"].map(fileURL)272 let mergedURL = a.values["--merged"].map(fileURL)273 if let m = mergedURL {274 guard let f = DocFormat(fileExtension: m.pathExtension), DocumentConverter.exportFormats.contains(f) else {275 throw CLIError(code: .usage, message: "cannot write “.\(m.pathExtension)” files (see `orixdocs formats`)")276 }277 }278 for url in [reportURL, mergedURL].compactMap({ $0 }) { try checkWritable(url, force: force) }279 let original = try readDocument(a.positionals[0]).document280 let revised = try readDocument(a.positionals[1]).document281 let result = DocumentComparer.compare(original: original, revised: revised)282 let names = (fileURL(a.positionals[0]).lastPathComponent, fileURL(a.positionals[1]).lastPathComponent)283 let s = result.summary284 if s.isIdentical { out("The documents are identical.") }285 else {286 out("\(s.totalChanges) change\(s.totalChanges == 1 ? "" : "s"): \(s.wordsInserted) word\(s.wordsInserted == 1 ? "" : "s") inserted, \(s.wordsDeleted) deleted, \(s.wordsMoved) moved; similarity \(Int((s.similarity * 100).rounded())) %")287 for kind in DocumentChange.Kind.allCases where s.count(kind) > 0 { out(" \(kind.rawValue): \(s.count(kind))") }288 }289 do {290 if let url = reportURL { try Data(result.reportMarkdown(originalName: names.0, revisedName: names.1).utf8).write(to: url, options: .atomic); err("report written to \(url.path)") }291 if let url = mergedURL { _ = try DocumentConverter.export(result.merged, to: url); err("merged document written to \(url.path)") }292 } catch { throw CLIError(code: .failure, message: "\(error)") }293 return .ok294}295296func formats(_ args: [String]) throws -> Exit {297 let a = try Arguments(args, flags: [], options: [])298 if a.wantsHelp { out("orixdocs formats\n\nLists the formats that can be read and written."); return .ok }299 try a.expect(0, "orixdocs formats")300 out("FORMAT EXTENSION READ WRITE NAME")301 for f in DocFormat.allCases {302 let r = DocumentConverter.importFormats.contains(f) ? "yes" : "no", w = DocumentConverter.exportFormats.contains(f) ? "yes" : "no"303 out("\(f.rawValue.padding(toLength: 11, withPad: " ", startingAt: 0))\(("." + f.fileExtension).padding(toLength: 12, withPad: " ", startingAt: 0))\(r.padding(toLength: 6, withPad: " ", startingAt: 0))\(w.padding(toLength: 7, withPad: " ", startingAt: 0))\(f.displayName)")304 }305 return .ok306}307308func workflowList(_ args: [String]) throws -> Exit {309 let a = try Arguments(args, flags: ["--json"], options: [])310 if a.wantsHelp { out(Help.workflow); return .ok }311 try a.expect(0, "orixdocs workflow list")312 let saved = WorkflowLibrary().entries()313 if a.flags.contains("--json") {314 struct Item: Codable { var id: String, name: String, summary: String, source: String; var steps: [String] }315 var items = BuiltinWorkflows.all.map { Item(id: $0.id, name: $0.name, summary: $0.summary, source: "builtin", steps: $0.steps.map(\.summary)) }316 items += saved.compactMap { e in e.workflow.map { Item(id: $0.id, name: $0.name, summary: $0.summary, source: e.url.path, steps: $0.steps.map(\.summary)) } }317 let enc = JSONEncoder(); enc.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]318 out(String(decoding: (try? enc.encode(items)) ?? Data("[]".utf8), as: UTF8.self))319 return .ok320 }321 out("Built-in workflows")322 for w in BuiltinWorkflows.all {323 out(" \(w.id) — \(w.name)")324 for (i, s) in w.steps.enumerated() { out(" \(i + 1). \(s.summary)") }325 }326 if !saved.isEmpty {327 out("\nSaved workflows (\(WorkflowLibrary().directory.path))")328 for e in saved {329 if let w = e.workflow { out(" \(e.url.lastPathComponent) — \(w.name) (\(w.steps.count) steps)") }330 else { out(" \(e.url.lastPathComponent) — not usable: \(e.problem ?? "")") }331 }332 }333 return .ok334}335336/// Holds the running task so the interrupt handler can cancel it.337final class Interrupt: @unchecked Sendable {338 private let lock = NSLock()339 private var task: Task<BatchResult, Never>?340 private(set) var fired = false341 func set(_ t: Task<BatchResult, Never>) { lock.lock(); task = t; lock.unlock() }342 func fire() { lock.lock(); fired = true; task?.cancel(); lock.unlock() }343}344345func workflowRun(_ args: [String]) async throws -> Exit {346 let a = try Arguments(args, flags: ["--force", "--quiet"], options: ["--out", "--jobs"])347 if a.wantsHelp { out(Help.workflow); return .ok }348 guard a.positionals.count >= 2 else { throw CLIError(code: .usage, message: "usage: orixdocs workflow run <workflow.json|builtin-name> <inputs…> --out <dir>") }349 guard let outPath = a.values["--out"] else { throw CLIError(code: .usage, message: "--out <dir> is required") }350 var jobs = min(8, ProcessInfo.processInfo.activeProcessorCount)351 if let j = a.values["--jobs"] {352 guard let n = Int(j), (1...64).contains(n) else { throw CLIError(code: .usage, message: "--jobs takes a number between 1 and 64") }353 jobs = n354 }355 let spec = a.positionals[0]356 let workflow: Workflow357 if let builtin = BuiltinWorkflows.named(spec) { workflow = builtin }358 else {359 let url = fileURL(spec)360 guard FileManager.default.fileExists(atPath: url.path) else {361 throw CLIError(code: .usage, message: "“\(spec)” is neither a built-in workflow (\(BuiltinWorkflows.all.map(\.id).joined(separator: ", "))) nor a file")362 }363 do { workflow = try Workflow.load(contentsOf: url) }364 catch { throw CLIError(code: .failure, message: "\(spec): \(error)") }365 }366 let inputs = a.positionals.dropFirst().map(fileURL)367 let quiet = a.flags.contains("--quiet")368 let runner = WorkflowRunner(outputDirectory: fileURL(outPath), existingFiles: a.flags.contains("--force") ? .overwrite : .fail, history: .shared)369370 let interrupt = Interrupt()371 signal(SIGINT, SIG_IGN)372 let source = DispatchSource.makeSignalSource(signal: SIGINT, queue: .global())373 source.setEventHandler { interrupt.fire() }374 source.resume()375376 let task = Task {377 await runner.runBatch(workflow, inputs: Array(inputs), maxConcurrent: jobs) { p in378 guard !quiet, let run = p.finished else { return }379 let mark = run.status == .succeeded ? "ok" : run.status.rawValue380 FileHandle.standardError.write(Data("[\(p.completedFiles)/\(p.fileCount)] \(mark) \(run.inputName) \(String(format: "%.2f s", run.duration))\n".utf8))381 }382 }383 interrupt.set(task)384 let result = await task.value385 source.cancel()386387 for run in result.runs {388 for path in run.outputs { out(path) }389 if let e = run.error { err(e.description) }390 for w in run.warnings where w.severity != .info && !quiet {391 FileHandle.standardError.write(Data("\(run.inputName): \(w.severity.rawValue): \(w.feature) — \(w.detail)\n".utf8))392 }393 }394 err("\(workflow.name): \(result.succeeded.count) succeeded, \(result.failed.count) failed, \(result.cancelled.count) cancelled in \(String(format: "%.2f s", result.duration))")395 if interrupt.fired || !result.cancelled.isEmpty { return .cancelled }396 if result.failed.isEmpty { return .ok }397 if result.failed.count == result.runs.count {398 return result.failed.allSatisfy({ $0.error?.kind == .outputExists }) ? .outputExists : .failure399 }400 return .partialFailure401}402403// MARK: Entry point404405func run(_ args: [String]) async throws -> Exit {406 guard let command = args.first else { out(Help.main); return .usage }407 let rest = Array(args.dropFirst())408 switch command {409 case "--version", "-V", "version": out("orixdocs \(AutomationReports.toolVersion)"); return .ok410 case "--help", "-h", "help": out(Help.main); return .ok411 case "convert": return try convert(rest)412 case "audit": return try audit(rest)413 case "stats": return try stats(rest)414 case "compare": return try compare(rest)415 case "formats": return try formats(rest)416 case "workflow":417 guard let sub = rest.first else { throw CLIError(code: .usage, message: "usage: orixdocs workflow run|list …") }418 switch sub {419 case "run": return try await workflowRun(Array(rest.dropFirst()))420 case "list": return try workflowList(Array(rest.dropFirst()))421 case "--help", "-h": out(Help.workflow); return .ok422 default: throw CLIError(code: .usage, message: "unknown workflow command “\(sub)” (run, list)")423 }424 default:425 throw CLIError(code: .usage, message: "unknown command “\(command)”. Try `orixdocs --help`.")426 }427}428429let code: Exit430do { code = try await run(Array(CommandLine.arguments.dropFirst())) }431catch let e as CLIError { err(e.message); code = e.code }432catch { err("\(error)"); code = .failure }433exit(code.rawValue)434