SPB Git

Repository Public

WorkflowRunner.swift 24.0 KB 430 lines swift

1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocAutomation/WorkflowRunner.swift3// Description: Executes workflows: one input or a batch with bounded concurrency, with progress, cooperative cancellation,4//              output-folder confinement and an execution record per input.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel10import DocContainer11import DocAudit12import DocLayout13import DocReferences14import DocTemplates1516public enum WorkflowInput: Sendable {17    case file(URL)18    /// A document already in memory (the one open in the application). `name` names the outputs.19    case document(DocumentModel, name: String)2021    var label: String {22        switch self {23        case .file(let url): return url.path24        case .document(_, let name): return name25        }26    }27    var baseName: String {28        switch self {29        case .file(let url): return url.deletingPathExtension().lastPathComponent30        case .document(_, let name): return name31        }32    }33}3435/// What to do when an output file already exists.36public enum ExistingFilePolicy: String, Sendable, Codable {37    /// Stop with an error (the default: nothing is overwritten unless asked).38    case fail39    case overwrite40    /// Write “name 2.pdf”, “name 3.pdf” …41    case rename42}4344/// The result of one run: its record, plus the document as the workflow left it and the findings of its last audit.45public struct WorkflowResult: Sendable {46    public var record: WorkflowRun47    public var document: DocumentModel?48    public var findings: [AuditFinding]49}5051public struct WorkflowRunner: Sendable {52    public var outputDirectory: URL53    public var existingFiles: ExistingFilePolicy54    /// Records every run when set.55    public var history: WorkflowHistoryStore?5657    public init(outputDirectory: URL, existingFiles: ExistingFilePolicy = .fail, history: WorkflowHistoryStore? = nil) {58        self.outputDirectory = outputDirectory; self.existingFiles = existingFiles; self.history = history59    }6061    // MARK: One input6263    /// Runs `workflow` on one input. Never throws: a failure or a cancellation is in the record.64    /// Cancellation is cooperative: the task's cancellation is checked before every step.65    public func run(_ workflow: Workflow, input: WorkflowInput, progress: (@Sendable (WorkflowProgress) -> Void)? = nil) async -> WorkflowResult {66        let started = Date()67        var state = StepState(input: input, outputDirectory: outputDirectory, existingFiles: existingFiles)68        var records: [WorkflowStepRecord] = workflow.steps.enumerated().map {69            WorkflowStepRecord(index: $0.offset, type: $0.element.type, name: $0.element.summary, outcome: .notRun, duration: 0, detail: "")70        }71        var failure: WorkflowError?72        var status = WorkflowRun.Status.succeeded7374        do { try workflow.validate() } catch {75            failure = WorkflowError(kind: .invalidWorkflow, stepIndex: nil, stepName: "", file: input.label, message: "\(error)")76            status = .failed77        }7879        if failure == nil {80            let count = workflow.steps.count81            for (i, step) in workflow.steps.enumerated() {82                if Task.isCancelled {83                    status = .cancelled84                    records[i].outcome = .cancelled85                    failure = WorkflowError(kind: .cancelled, stepIndex: i, stepName: step.summary, file: input.label, message: "Cancelled before this step.")86                    break87                }88                progress?(WorkflowProgress(input: input.label, stepIndex: i, stepCount: count, stepName: step.summary, phase: .started, fraction: Double(i) / Double(count)))89                let t0 = Date()90                do {91                    let outcome = try state.perform(step, index: i)92                    records[i].outcome = outcome.skipped ? .skipped : .succeeded93                    records[i].detail = outcome.detail94                } catch let e as WorkflowError {95                    records[i].outcome = .failed; records[i].detail = e.message96                    failure = e; status = .failed97                } catch {98                    let e = WorkflowError(kind: .operationFailed, stepIndex: i, stepName: step.summary, file: input.label, message: "\(error)")99                    records[i].outcome = .failed; records[i].detail = e.message100                    failure = e; status = .failed101                }102                records[i].duration = Date().timeIntervalSince(t0)103                if failure != nil { break }104                progress?(WorkflowProgress(input: input.label, stepIndex: i, stepCount: count, stepName: step.summary, phase: .finished, fraction: Double(i + 1) / Double(count)))105                await Task.yield()106            }107        }108109        let record = WorkflowRun(id: DocID.make(), workflowID: workflow.id, workflowName: workflow.name, input: input.label, started: started, ended: Date(),110                                 status: status, steps: records, warnings: state.warnings, outputs: state.outputs.map(\.path),111                                 audit: state.audited ? AuditSummary(state.findings) : nil, error: failure)112        history?.append(record)113        return WorkflowResult(record: record, document: state.document, findings: state.findings)114    }115116    // MARK: Batch117118    /// Runs `workflow` over many files, at most `maxConcurrent` at a time. A file that fails does not stop the others;119    /// every input gets a record. Cancelling the task stops starting new files and cancels the ones in flight.120    public func runBatch(_ workflow: Workflow, inputs: [URL], maxConcurrent: Int = 4, progress: (@Sendable (BatchProgress) -> Void)? = nil) async -> BatchResult {121        let started = Date()122        let limit = max(1, min(maxConcurrent, 64))123        var runs = [WorkflowRun?](repeating: nil, count: inputs.count)124        var next = 0125        var completed = 0126        let total = inputs.count127128        await withTaskGroup(of: (Int, WorkflowRun).self) { group in129            func start(_ index: Int) {130                let url = inputs[index]131                group.addTask {132                    let result = await self.run(workflow, input: .file(url)) { step in133                        progress?(BatchProgress(fileIndex: index, fileCount: total, input: url, step: step, finished: nil, completedFiles: -1))134                    }135                    return (index, result.record)136                }137            }138            while next < min(limit, total) { start(next); next += 1 }139            for await (index, record) in group {140                runs[index] = record141                completed += 1142                progress?(BatchProgress(fileIndex: index, fileCount: total, input: inputs[index], step: nil, finished: record, completedFiles: completed))143                if next < total, !Task.isCancelled { start(next); next += 1 }144            }145        }146147        let now = Date()148        let all: [WorkflowRun] = runs.enumerated().map { i, run in149            if let run { return run }150            // Never started: the batch was cancelled first.151            let e = WorkflowError(kind: .cancelled, stepIndex: nil, stepName: "", file: inputs[i].path, message: "Cancelled before this file was started.")152            let record = WorkflowRun(id: DocID.make(), workflowID: workflow.id, workflowName: workflow.name, input: inputs[i].path, started: now, ended: now,153                                     status: .cancelled, steps: [], warnings: [], outputs: [], audit: nil, error: e)154            history?.append(record)155            return record156        }157        return BatchResult(runs: all, started: started, ended: Date())158    }159}160161// MARK: - Step execution162163/// The document being processed and everything the steps accumulate.164struct StepState {165    let input: WorkflowInput166    let outputDirectory: URL167    let existingFiles: ExistingFilePolicy168    var document: DocumentModel?169    var warnings: [WorkflowWarning] = []170    var findings: [AuditFinding] = []171    var audited = false172    var outputs: [URL] = []173174    struct Outcome { var detail: String; var skipped = false }175176    init(input: WorkflowInput, outputDirectory: URL, existingFiles: ExistingFilePolicy) {177        self.input = input; self.outputDirectory = outputDirectory; self.existingFiles = existingFiles178        if case .document(let doc, _) = input { document = doc }179    }180181    private func error(_ kind: WorkflowError.Kind, _ index: Int, _ step: WorkflowStep, _ message: String) -> WorkflowError {182        WorkflowError(kind: kind, stepIndex: index, stepName: step.summary, file: input.label, message: message)183    }184185    private func plural(_ n: Int, _ one: String, _ many: String) -> String { "\(n) \(n == 1 ? one : many)" }186187    mutating func perform(_ step: WorkflowStep, index i: Int) throws -> Outcome {188        if case .importDocument(let path) = step { return try importDocument(path: path, step: step, index: i) }189        guard var doc = document else {190            throw error(.missingInput, i, step, "There is no document yet: the workflow must start with an import step.")191        }192        defer { document = doc }193        switch step {194        case .importDocument:195            return Outcome(detail: "")196        case .applyTheme(let name):197            guard let theme = Theme.named(name) else { throw error(.operationFailed, i, step, "Unknown theme “\(name)”.") }198            let before = doc.styles.themeName199            doc.styles.applyTheme(theme)200            return Outcome(detail: before == theme.name ? "The document already used this theme." : "Theme “\(before)” replaced by “\(theme.name)”.")201        case .applyTemplateStyles(let id):202            guard let template = TemplateLibrary.template(id: id) else { throw error(.operationFailed, i, step, "Unknown template “\(id)”.") }203            return applyTemplateStyles(template, to: &doc)204        case .setPageSetup(let options):205            return try setPageSetup(options, on: &doc, step: step, index: i)206        case .acceptAllChanges, .rejectAllChanges:207            let n = doc.trackedChanges().count208            guard n > 0 else { return Outcome(detail: "No tracked changes.", skipped: true) }209            let accept = step == .acceptAllChanges210            doc.resolveChanges(accept: accept)211            return Outcome(detail: "\(plural(n, "change", "changes")) \(accept ? "accepted" : "rejected").")212        case .removeComments:213            let n = doc.comments.count214            var anchored = 0215            doc.mutateEveryParagraph { p in216                for r in p.runs.indices where !p.runs[r].comments.isEmpty { p.runs[r].comments = []; anchored += 1 }217            }218            doc.comments = []219            guard n > 0 || anchored > 0 else { return Outcome(detail: "No comments.", skipped: true) }220            return Outcome(detail: "\(plural(n, "comment", "comments")) removed.")221        case .tableOfContents(let title, let maxLevel):222            return tableOfContents(title: title, maxLevel: maxLevel, in: &doc)223        case .insertBibliography(let title):224            let cited = Numbering(doc).citedKeys225            if cited.isEmpty { return Outcome(detail: "The document cites no source.", skipped: true) }226            if doc.body.contains(where: { if case .bibliography = $0 { return true } else { return false } }) {227                return Outcome(detail: "The document already has a bibliography.", skipped: true)228            }229            let french = doc.meta.language.lowercased().hasPrefix("fr")230            doc.body.append(.bibliography(BibliographyBlock(title: title ?? (french ? "Références" : "References"))))231            let missing = cited.filter { doc.bibEntry($0) == nil }232            if !missing.isEmpty {233                warnings.append(WorkflowWarning(stepIndex: i, severity: .approximated, feature: "Bibliography",234                                                detail: "Cited keys without a reference: " + missing.prefix(12).joined(separator: ", "), count: missing.count))235            }236            return Outcome(detail: "Bibliography added for \(plural(cited.count, "cited source", "cited sources")).")237        case .setCitationStyle(let id):238            guard CitationEngine.styles.contains(where: { $0.id == id }) else { throw error(.operationFailed, i, step, "Unknown citation style “\(id)”.") }239            doc.settings.citationStyle = id240            return Outcome(detail: "Citation style set to \(id).")241        case .recalculateTables:242            let formulas = doc.body.reduce(0) { n, b in n + (b.table?.rows.reduce(0) { $0 + $1.cells.filter { $0.formula != nil }.count } ?? 0) }243            guard formulas > 0 else { return Outcome(detail: "No table formulas.", skipped: true) }244            var editor = DocumentEditor(doc: doc)245            editor.recalculateAllTables()246            doc = editor.doc247            return Outcome(detail: "\(plural(formulas, "formula", "formulas")) recalculated.")248        case .setMetadata(let m):249            var changed: [String] = []250            if let v = m.title { doc.meta.title = v; changed.append("title") }251            if let v = m.author { doc.meta.author = v; changed.append("author") }252            if let v = m.subject { doc.meta.subject = v; changed.append("subject") }253            if let v = m.keywords { doc.meta.keywords = v; changed.append("keywords") }254            if let v = m.language { doc.meta.language = v; changed.append("language") }255            doc.meta.modified = Date()256            return Outcome(detail: changed.isEmpty ? "Nothing to set." : "Set: " + changed.joined(separator: ", ") + ".", skipped: changed.isEmpty)257        case .audit(let profile, let failOnErrors):258            findings = AutomationReports.audit(doc, profile: profile)259            audited = true260            let s = AuditSummary(findings)261            let detail = "\(plural(s.errors, "error", "errors")), \(plural(s.warnings, "warning", "warnings")), \(plural(s.infos, "note", "notes"))."262            if failOnErrors, s.errors > 0 {263                let first = findings.first { $0.severity == .error }.map { " First: \($0.title)." } ?? ""264                throw error(.auditFailed, i, step, "The audit found \(plural(s.errors, "error", "errors")).\(first)")265            }266            return Outcome(detail: detail)267        case .export(let format, let fileName, let pdf):268            let url = try destination(fileName: fileName, fileExtension: format.fileExtension, suffix: "", step: step, index: i)269            do {270                let result = try DocumentConverter.export(doc, format: format, pdfOptions: pdf?.pdfOptions ?? PDFOptions())271                try result.data.write(to: url, options: .atomic)272                warnings += result.warnings.map { WorkflowWarning($0, step: i) }273                outputs.append(url)274                return Outcome(detail: "\(url.lastPathComponent) (\(ByteCountFormatter.string(fromByteCount: Int64(result.data.count), countStyle: .file)))")275            } catch let e as WorkflowError { throw e } catch let e {276                throw error(.exportFailed, i, step, "\(e)")277            }278        case .writeAuditReport(let format, let fileName):279            guard audited else { return Outcome(detail: "No audit step ran before this one.", skipped: true) }280            let isJSON = format.lowercased() == "json"281            guard isJSON || DocFormat(rawValue: format) != nil || DocFormat(fileExtension: format) != nil else {282                throw error(.operationFailed, i, step, "Unknown report format “\(format)”.")283            }284            let docFormat = DocFormat(rawValue: format) ?? DocFormat(fileExtension: format) ?? .markdown285            let url = try destination(fileName: fileName, fileExtension: isJSON ? "json" : docFormat.fileExtension, suffix: "-audit", step: step, index: i)286            do {287                let data: Data288                if isJSON { data = try AutomationReports.auditJSON(findings, input: input.label) }289                else { data = try DocumentConverter.export(DocumentAuditor.reportDocument(findings, for: doc), format: docFormat).data }290                try data.write(to: url, options: .atomic)291                outputs.append(url)292                return Outcome(detail: url.lastPathComponent)293            } catch let e {294                throw error(.exportFailed, i, step, "\(e)")295            }296        }297    }298299    // MARK: Steps300301    private mutating func importDocument(path: String?, step: WorkflowStep, index i: Int) throws -> Outcome {302        let url: URL303        if let path { url = URL(fileURLWithPath: (path as NSString).expandingTildeInPath) }304        else {305            switch input {306            case .file(let u): url = u307            case .document(let doc, let name):308                document = doc309                return Outcome(detail: "Using the open document “\(name)”.")310            }311        }312        do {313            let result = try DocumentConverter.importDocument(at: url)314            document = result.document315            warnings += result.warnings.map { WorkflowWarning($0, step: i) }316            return Outcome(detail: "\(plural(result.document.body.count, "block", "blocks"))" + (result.warnings.isEmpty ? "." : ", \(plural(result.warnings.count, "import warning", "import warnings"))."))317        } catch let e as CocoaError where e.code == .fileReadNoSuchFile || e.code == .fileNoSuchFile {318            throw error(.importFailed, i, step, "The file does not exist.")319        } catch let e {320            throw error(.importFailed, i, step, "\(e)")321        }322    }323324    /// The template's style sheet replaces the document's. Paragraphs keep their style id, so a "Heading 1" takes the template's325    /// "Heading 1"; styles the template does not define are carried over unchanged, so no paragraph loses its style.326    private func applyTemplateStyles(_ template: DocumentTemplate, to doc: inout DocumentModel) -> Outcome {327        let context = TemplateContext(author: doc.meta.author, language: doc.meta.language, paper: doc.pageSetup.paper)328        var sheet = template.make(context).styles329        var used = Set<String>()330        doc.forEachParagraphEverywhere { p, _, _ in331            used.insert(p.style)332            for r in p.runs { if let c = r.charStyle { used.insert(c) } }333        }334        var carried = 0335        for style in doc.styles.styles where sheet.style(style.id) == nil {336            // Keep custom styles in use, and their parents.337            let needed = used.contains(style.id) || doc.styles.styles.contains { used.contains($0.id) && doc.styles.chain($0.id).contains { $0.id == style.id } }338            if needed { sheet.upsert(style); carried += 1 }339        }340        let mapped = used.filter { template.make(context).styles.style($0) != nil }.count341        doc.styles = sheet342        return Outcome(detail: "\(plural(mapped, "style", "styles")) in use taken from the template" + (carried > 0 ? ", \(carried) kept from the document." : "."))343    }344345    private func setPageSetup(_ o: PageSetupOptions, on doc: inout DocumentModel, step: WorkflowStep, index i: Int) throws -> Outcome {346        var paper: PaperSize?347        if let name = o.paper {348            guard let p = PageSetupOptions.paperSize(named: name) else { throw error(.operationFailed, i, step, "Unknown paper “\(name)”.") }349            paper = p350        }351        let sections = doc.sectionSetups.count352        for s in 0..<sections {353            var setup = doc.setup(ofSection: s)354            if let paper { setup.paper = paper }355            if let d = o.orientation?.lowercased() { setup.landscape = d == "landscape" }356            if let m = o.margins { setup.margins = Insets(all: m) }357            if let m = o.marginTop { setup.margins.top = m }358            if let m = o.marginBottom { setup.margins.bottom = m }359            if let m = o.marginLeft { setup.margins.left = m }360            if let m = o.marginRight { setup.margins.right = m }361            doc.setSetup(setup, ofSection: s)362        }363        return Outcome(detail: "Applied to \(plural(sections, "section", "sections")).")364    }365366    private func tableOfContents(title: String?, maxLevel: Int, in doc: inout DocumentModel) -> Outcome {367        let level = max(1, min(9, maxLevel))368        if let existing = doc.body.firstIndex(where: { if case .toc(let t) = $0 { return t.kind == .contents } else { return false } }),369           case .toc(var toc) = doc.body[existing] {370            toc.maxLevel = level371            if let title { toc.title = title }372            doc.body[existing] = .toc(toc)373            return Outcome(detail: "The existing table of contents was refreshed (levels 1–\(level)).")374        }375        let headings = Numbering(doc).outline.filter { $0.level <= level }.count376        guard headings > 0 else { return Outcome(detail: "The document has no headings: no table of contents inserted.", skipped: true) }377        // After the title block (title, subtitle, author lines directly under them), before the first heading at the latest.378        var at = 0379        let front: Set<String> = [StyleID.title, StyleID.subtitle]380        while at < doc.body.count, let p = doc.body[at].paragraph, front.contains(p.style) { at += 1 }381        let french = doc.meta.language.lowercased().hasPrefix("fr")382        doc.body.insert(.toc(TOCBlock(kind: .contents, title: title ?? (french ? "Table des matières" : "Contents"), maxLevel: level)), at: at)383        return Outcome(detail: "Table of contents inserted (\(plural(headings, "entry", "entries"))).")384    }385386    // MARK: Output paths387388    /// Resolves an output name inside the output folder; refuses anything that would land outside it or on the input file.389    private func destination(fileName: String?, fileExtension ext: String, suffix: String, step: WorkflowStep, index i: Int) throws -> URL {390        let fm = FileManager.default391        do { try fm.createDirectory(at: outputDirectory, withIntermediateDirectories: true) } catch {392            throw self.error(.exportFailed, i, step, "The output folder cannot be created: \(error.localizedDescription)")393        }394        let root = outputDirectory.resolvingSymlinksInPath().standardizedFileURL395        let base = input.baseName.replacingOccurrences(of: "/", with: "-").replacingOccurrences(of: ":", with: "-")396        var name = (fileName ?? "{name}\(suffix)").replacingOccurrences(of: "{name}", with: base.isEmpty ? "document" : base)397        if (name as NSString).pathExtension.lowercased() != ext.lowercased() { name += "." + ext }398        do { try Workflow.checkRelative(name, step: i) } catch {399            throw self.error(.pathEscapesOutputFolder, i, step, "“\(name)” is not a location inside the output folder.")400        }401        var url = root.appendingPathComponent(name).standardizedFileURL402        let parent = url.deletingLastPathComponent()403        if parent.path != root.path {404            do { try fm.createDirectory(at: parent, withIntermediateDirectories: true) } catch {405                throw self.error(.exportFailed, i, step, "The folder “\(parent.lastPathComponent)” cannot be created: \(error.localizedDescription)")406            }407        }408        // A symbolic link inside the output folder must not lead out of it.409        let realParent = parent.resolvingSymlinksInPath().standardizedFileURL.path410        guard realParent == root.path || realParent.hasPrefix(root.path + "/") else {411            throw self.error(.pathEscapesOutputFolder, i, step, "“\(name)” resolves to a location outside the output folder.")412        }413        if case .file(let source) = input, source.resolvingSymlinksInPath().standardizedFileURL.path == url.resolvingSymlinksInPath().path {414            throw self.error(.outputExists, i, step, "The output would replace its own input file “\(source.lastPathComponent)”. Choose another output folder.")415        }416        if fm.fileExists(atPath: url.path) {417            switch existingFiles {418            case .overwrite: break419            case .fail:420                throw self.error(.outputExists, i, step, "“\(url.lastPathComponent)” already exists in the output folder. Nothing was overwritten.")421            case .rename:422                let stem = url.deletingPathExtension().lastPathComponent423                var n = 2424                repeat { url = parent.appendingPathComponent("\(stem) \(n).\(ext)"); n += 1 } while fm.fileExists(atPath: url.path) && n < 10_000425            }426        }427        return url428    }429}430
Files main
Menu

Theme