SPB Git

Repository Public

main.swift 20.3 KB 434 lines swift

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

Theme