Repository Public
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