Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocAudit/DocumentAuditor.swift3// Description: The document quality auditor: runs the enabled checks and returns findings with evidence, location, severity,4// explanation and suggested correction, in a deterministic order.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel1011public enum DocumentAuditor {12 /// Audits a document.13 /// - Parameters:14 /// - layout: facts from the pagination; checks that need them fall back to what the model alone shows, or are skipped.15 /// - incompleteReference: returns the names of the fields a reference lacks (injected by the app from the reference engine);16 /// `incompleteReference` is skipped when nil.17 /// - Returns: findings sorted by position in the document, then by check. The result is the same for the same input.18 public static func audit(_ doc: DocumentModel, layout: LayoutFacts? = nil, options: AuditOptions = .init(),19 incompleteReference: ((BibEntry) -> [String])? = nil) -> [AuditFinding] {20 var run = AuditRun(doc: doc, layout: layout, options: options)21 run.runAll(incompleteReference: incompleteReference)22 return run.sortedFindings()23 }24}2526struct AuditRun {27 let doc: DocumentModel28 let layout: LayoutFacts?29 let options: AuditOptions30 let french: Bool31 let numbering: Numbering32 let refs: [ParagraphRef]33 var levels: HeadingLevels34 var findings: [AuditFinding] = []3536 init(doc: DocumentModel, layout: LayoutFacts?, options: AuditOptions) {37 self.doc = doc; self.layout = layout; self.options = options38 french = AuditTexts.isFrench(options.language ?? doc.meta.language)39 numbering = Numbering(doc)40 refs = Scan.paragraphs(of: doc)41 levels = HeadingLevels(doc)42 }4344 func t(_ en: String, _ fr: String) -> String { french ? fr : en }45 func quote(_ s: String) -> String { french ? "« \(s) »" : "“\(s)”" }4647 // MARK: Plumbing4849 func location(_ story: StoryID, _ path: ParaPath?, _ p: Paragraph?, excerpt: String? = nil) -> AuditLocation {50 var page: Int?51 if story == .body, let path, doc.body.indices.contains(path.block) { page = layout?.pageOfBlock[doc.body[path.block].id] }52 return AuditLocation(story: story, path: path, paragraphID: p?.id, page: page, excerpt: excerpt ?? p.map { Scan.excerpt($0) } ?? "")53 }5455 func location(_ ref: ParagraphRef, excerpt: String? = nil) -> AuditLocation { location(ref.story, ref.path, ref.paragraph, excerpt: excerpt) }5657 func blockLocation(_ index: Int, excerpt: String) -> AuditLocation {58 AuditLocation(story: .body, path: ParaPath(block: index), paragraphID: doc.body[index].paragraph?.id, page: layout?.pageOfBlock[doc.body[index].id], excerpt: excerpt)59 }6061 mutating func add(_ check: AuditCheck, _ key: String, _ severity: AuditFinding.Severity, evidence: String, location: AuditLocation?,62 explanation: String? = nil, suggestion: String? = nil) {63 let text = AuditTexts.text(check, french: french)64 findings.append(AuditFinding(id: "\(check.rawValue)/\(key)", check: check, severity: severity, title: text.title, explanation: explanation ?? text.explanation,65 evidence: evidence, suggestion: suggestion ?? text.suggestion, location: location))66 }6768 func sortedFindings() -> [AuditFinding] {69 let order = Dictionary(uniqueKeysWithValues: AuditCheck.allCases.enumerated().map { ($1, $0) })70 func key(_ f: AuditFinding) -> (String, String, Int, String) {71 guard let l = f.location, let path = l.path else { return ("", "", order[f.check]!, f.id) }72 return (l.story.sortKey, path.sortKey, order[f.check]!, f.id)73 }74 // Per-check cap, applied in document order.75 var kept: [AuditFinding] = []76 var counts: [AuditCheck: Int] = [:]77 var dropped: [AuditCheck: (count: Int, first: AuditFinding)] = [:]78 for f in findings.sorted(by: { key($0) < key($1) }) {79 counts[f.check, default: 0] += 180 if counts[f.check]! <= options.maxFindingsPerCheck { kept.append(f) } else if let d = dropped[f.check] { dropped[f.check] = (d.count + 1, d.first) } else { dropped[f.check] = (1, f) }81 }82 for check in AuditCheck.allCases {83 guard let d = dropped[check] else { continue }84 var f = d.first85 f.id = "\(check.rawValue)/+more"86 f.severity = .info87 f.evidence = t("\(d.count) more findings of this kind were not listed; the first of them: \(d.first.evidence)",88 "\(d.count) autres constats de ce type ne sont pas listés ; le premier d'entre eux : \(d.first.evidence)")89 kept.append(f)90 }91 return kept.sorted(by: { key($0) < key($1) })92 }9394 mutating func runAll(incompleteReference: ((BibEntry) -> [String])?) {95 let on = options.enabled96 if on.contains(.missingHeadings) { missingHeadings() }97 if on.contains(.headingHierarchy) || on.contains(.emptyHeading) || on.contains(.duplicateHeading) { headings() }98 if on.contains(.brokenCrossReference) { brokenCrossReferences() }99 if on.contains(.missingFigureCaption) || on.contains(.missingTableCaption) { captions() }100 if on.contains(.missingAltText) { altText() }101 if on.contains(.inconsistentFormatting) { inconsistentFormatting() }102 if on.contains(.unresolvedComment) { comments() }103 if on.contains(.pendingTrackedChange) { trackedChanges() }104 if on.contains(.missingBibliographyEntry) || on.contains(.orphanedCitation) || on.contains(.incompleteReference) { citations(incompleteReference) }105 if on.contains(.unusualPageBreak) { pageBreaks() }106 if on.contains(.overflowingTable) { overflowingTables() }107 if on.contains(.missingPageNumbers) { pageNumbers() }108 if on.contains(.undefinedAcronym) { acronyms() }109 if on.contains(.unreferencedFigure) || on.contains(.unreferencedTable) { unreferencedCaptions() }110 if on.contains(.repeatedWording) { repeatedWording() }111 if on.contains(.longSentence) || on.contains(.doubleSpaces) { sentencesAndSpaces() }112 if on.contains(.missingMetadata) { metadata() }113 }114115 // MARK: Headings116117 private var bodyWordCount: Int {118 var n = 0119 doc.forEachBodyParagraph { p, _ in n += Scan.wordCount(p.visibleText) }120 return n121 }122123 private mutating func missingHeadings() {124 guard numbering.outline.isEmpty else { return }125 let words = bodyWordCount126 guard words >= options.longDocumentWords else { return }127 let paragraphs = doc.body.filter { $0.paragraph.map { !$0.visibleText.isEmpty } ?? false }.count128 let first = refs.first { $0.story == .body && !$0.paragraph.visibleText.isEmpty }129 add(.missingHeadings, "document", .warning,130 evidence: t("\(words) words in \(paragraphs) paragraphs, 0 headings (threshold: \(options.longDocumentWords) words).",131 "\(words) mots en \(paragraphs) paragraphes, 0 titre (seuil : \(options.longDocumentWords) mots)."),132 location: first.map { location($0) } ?? AuditLocation())133 }134135 private mutating func headings() {136 var previous: Int?137 var minLevel = 10138 struct Entry { var index: Int; var p: Paragraph; var level: Int; var text: String }139 var entries: [Entry] = []140 for (bi, block) in doc.body.enumerated() {141 guard case .paragraph(let p) = block else { continue }142 let level = levels.level(p)143 guard level > 0 else { continue }144 let text = p.visibleText.trimmingCharacters(in: .whitespacesAndNewlines)145 if text.isEmpty {146 let hasObject = p.runs.contains { r in147 guard !r.isDeleted, let i = r.inline else { return false }148 if case .bookmark = i { return false }149 return true150 }151 if !hasObject && options.enabled.contains(.emptyHeading) {152 add(.emptyHeading, p.id, .warning,153 evidence: t("Empty paragraph of style \(p.style) (level \(level)), block \(bi + 1).", "Paragraphe vide de style \(p.style) (niveau \(level)), bloc \(bi + 1)."),154 location: blockLocation(bi, excerpt: ""))155 }156 continue157 }158 entries.append(Entry(index: bi, p: p, level: level, text: text))159 minLevel = min(minLevel, level)160 }161 if options.enabled.contains(.headingHierarchy) {162 for e in entries {163 if let prev = previous {164 if e.level > prev + 1 {165 add(.headingHierarchy, e.p.id, .warning,166 evidence: t("\(quote(Scan.short(e.text, limit: 80))) is level \(e.level) but follows a level \(prev) heading (level \(prev + 1) is skipped).",167 "\(quote(Scan.short(e.text, limit: 80))) est de niveau \(e.level) mais suit un titre de niveau \(prev) (le niveau \(prev + 1) est sauté)."),168 location: blockLocation(e.index, excerpt: Scan.short(e.text)))169 }170 } else if e.level > minLevel {171 add(.headingHierarchy, e.p.id, .warning,172 evidence: t("The first heading, \(quote(Scan.short(e.text, limit: 80))), is level \(e.level) while the document uses level \(minLevel) further on.",173 "Le premier titre, \(quote(Scan.short(e.text, limit: 80))), est de niveau \(e.level) alors que le document utilise le niveau \(minLevel) plus loin."),174 location: blockLocation(e.index, excerpt: Scan.short(e.text)))175 }176 previous = e.level177 }178 }179 if options.enabled.contains(.duplicateHeading) {180 var stack: [(level: Int, id: String)] = []181 var seen: [String: Entry] = [:]182 for e in entries {183 while let last = stack.last, last.level >= e.level { stack.removeLast() }184 let key = "\(stack.last?.id ?? "")|\(e.level)|\(Scan.folded(e.text))"185 if let first = seen[key] {186 add(.duplicateHeading, e.p.id, .info,187 evidence: t("\(quote(Scan.short(e.text, limit: 80))) (level \(e.level)) appears at block \(first.index + 1) and again at block \(e.index + 1), under the same parent.",188 "\(quote(Scan.short(e.text, limit: 80))) (niveau \(e.level)) figure au bloc \(first.index + 1) puis de nouveau au bloc \(e.index + 1), sous le même parent."),189 location: blockLocation(e.index, excerpt: Scan.short(e.text)))190 } else { seen[key] = e }191 stack.append((e.level, e.p.id))192 }193 }194 }195196 // MARK: References197198 private mutating func brokenCrossReferences() {199 for ref in refs {200 var n = 0201 for r in ref.paragraph.runs where !r.isDeleted {202 if case .crossRef(let x)? = r.inline, !numbering.targetExists(x.target) {203 n += 1204 add(.brokenCrossReference, "\(ref.paragraph.id)/\(n)/\(x.target)", .error,205 evidence: t("Cross-reference (\(x.display.rawValue)) to target \(quote(x.target)), which does not exist, in: \(quote(Scan.excerpt(ref.paragraph, limit: 90))).",206 "Renvoi (\(x.display.rawValue)) vers la cible \(quote(x.target)), inexistante, dans : \(quote(Scan.excerpt(ref.paragraph, limit: 90)))."),207 location: location(ref))208 }209 if let link = r.props.link, link.hasPrefix("#"), link.count > 1 {210 let name = String(link.dropFirst())211 if !numbering.targetExists(name) {212 n += 1213 add(.brokenCrossReference, "\(ref.paragraph.id)/\(n)/\(name)", .error,214 evidence: t("Internal link on \(quote(Scan.short(r.text, limit: 60))) to bookmark \(quote(name)), which does not exist.",215 "Lien interne sur \(quote(Scan.short(r.text, limit: 60))) vers le signet \(quote(name)), inexistant."),216 location: location(ref))217 }218 }219 }220 }221 }222223 static let figureLabels: Set<String> = ["figure", "fig", "fig.", "illustration", "image", "graphique", "chart", "photo", "schema", "scheme", "diagram", "diagramme", "carte", "map"]224 static let tableLabels: Set<String> = ["table", "tableau", "tab", "tab."]225226 private func captionLabel(_ index: Int) -> String? {227 guard doc.body.indices.contains(index), case .paragraph(let p) = doc.body[index], let c = numbering.captions[p.id] else { return nil }228 return Scan.folded(c.label)229 }230231 private func isImageParagraph(_ p: Paragraph) -> Bool {232 var images = 0233 for r in p.runs where !r.isDeleted {234 if let i = r.inline {235 switch i {236 case .image: images += 1237 case .bookmark: break238 default: return false239 }240 } else if !r.text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { return false }241 }242 return images > 0243 }244245 private mutating func captions() {246 let body = doc.body247 let anyTableCaption = numbering.captions.values.contains { AuditRun.tableLabels.contains(Scan.folded($0.label)) }248 func unnumberedCaption(_ index: Int) -> Bool {249 guard body.indices.contains(index), case .paragraph(let p) = body[index] else { return false }250 return p.style == StyleID.caption && numbering.captions[p.id] == nil && !p.visibleText.isEmpty251 }252 for (bi, block) in body.enumerated() {253 switch block {254 case .paragraph(let p):255 guard options.enabled.contains(.missingFigureCaption), isImageParagraph(p) else { continue }256 // Several images in a row share the caption that precedes or follows the group.257 var lo = bi, hi = bi258 while lo > 0, case .paragraph(let q) = body[lo - 1], isImageParagraph(q) { lo -= 1 }259 while hi + 1 < body.count, case .paragraph(let q) = body[hi + 1], isImageParagraph(q) { hi += 1 }260 let labels = [captionLabel(lo - 1), captionLabel(hi + 1)].compactMap { $0 }261 if labels.contains(where: { AuditRun.figureLabels.contains($0) }) { continue }262 let images = p.runs.compactMap { r -> ImageObject? in if !r.isDeleted, case .image(let i)? = r.inline { return i } else { return nil } }263 var evidence = t("Block \(bi + 1) holds only an image (asset \(images[0].asset), \(Int(images[0].width)) × \(Int(images[0].height)) pt); the blocks before and after it are not figure captions.",264 "Le bloc \(bi + 1) ne contient qu'une image (ressource \(images[0].asset), \(Int(images[0].width)) × \(Int(images[0].height)) pt) ; les blocs voisins ne sont pas des légendes de figure.")265 if unnumberedCaption(lo - 1) || unnumberedCaption(hi + 1) {266 evidence += t(" A neighbouring paragraph uses the Caption style but has no figure number field.", " Un paragraphe voisin utilise le style Légende, mais sans champ de numéro de figure.")267 }268 add(.missingFigureCaption, p.id, .warning, evidence: evidence,269 location: blockLocation(bi, excerpt: images[0].altText.isEmpty ? t("[image]", "[image]") : images[0].altText))270 case .table(let tb):271 guard options.enabled.contains(.missingTableCaption), tb.rows.count >= 2, tb.columnCount >= 2 else { continue }272 let labels = [captionLabel(bi - 1), captionLabel(bi + 1)].compactMap { $0 }273 if labels.contains(where: { AuditRun.tableLabels.contains($0) }) { continue }274 let head = tb.rows[0].cells.map { $0.plainText.replacingOccurrences(of: objectReplacementCharacter, with: "") }.joined(separator: " | ")275 var evidence = t("Table of \(tb.rows.count) rows × \(tb.columnCount) columns at block \(bi + 1) (first row: \(quote(Scan.short(head, limit: 80)))); the blocks before and after it are not table captions.",276 "Tableau de \(tb.rows.count) lignes × \(tb.columnCount) colonnes au bloc \(bi + 1) (première ligne : \(quote(Scan.short(head, limit: 80)))) ; les blocs voisins ne sont pas des légendes de tableau.")277 if unnumberedCaption(bi - 1) || unnumberedCaption(bi + 1) {278 evidence += t(" A neighbouring paragraph uses the Caption style but has no table number field.", " Un paragraphe voisin utilise le style Légende, mais sans champ de numéro de tableau.")279 }280 add(.missingTableCaption, tb.id, options.requireTableCaptions || anyTableCaption ? .warning : .info, evidence: evidence,281 location: blockLocation(bi, excerpt: Scan.short(head)))282 default: break283 }284 }285 }286287 private mutating func altText() {288 for ref in refs {289 var n = 0290 for r in ref.paragraph.runs where !r.isDeleted {291 guard case .image(let img)? = r.inline else { continue }292 n += 1293 guard img.altText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { continue }294 add(.missingAltText, "\(ref.paragraph.id)/\(n)", .warning,295 evidence: t("Image \(n) of the paragraph (asset \(img.asset), \(Int(img.width)) × \(Int(img.height)) pt) has an empty alternative text.",296 "L'image \(n) du paragraphe (ressource \(img.asset), \(Int(img.width)) × \(Int(img.height)) pt) a un texte de remplacement vide."),297 location: location(ref, excerpt: Scan.excerpt(ref.paragraph).isEmpty ? "[image]" : nil))298 }299 }300 }301302 // MARK: Formatting consistency303304 /// A paragraph deviates when, for one attribute, at least `formattingDominance` of the non-empty paragraphs of its style305 /// (in a group of at least `formattingMinGroup`) share one value and this paragraph has another one.306 /// Character attributes (font, size, colour) count only when they cover `formattingUniformShare` of the paragraph, so a few307 /// emphasised words never make a paragraph "different". Bold, italic and underline are not compared at all.308 private mutating func inconsistentFormatting() {309 struct Sample { var ref: ParagraphRef; var values: [String?] }310 let attributes = [t("font", "police"), t("font size", "taille de police"), t("text colour", "couleur du texte"), t("alignment", "alignement"),311 t("left indent", "retrait gauche"), t("first-line indent", "retrait de première ligne"), t("line spacing", "interligne")]312 var charCache: [String: ResolvedChar] = [:]313 var groups: [String: [Sample]] = [:]314 var groupOrder: [String] = []315 for ref in refs where ref.story == .body {316 let p = ref.paragraph317 let visible = p.visibleText318 if visible.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { continue }319 // Character attributes: value → characters carrying it.320 var fonts: [String: Int] = [:], sizes: [String: Int] = [:], colours: [String: Int] = [:]321 var total = 0322 for r in p.runs where !r.isDeleted && r.inline == nil {323 let n = r.text.unicodeScalars.reduce(0) { $0 + (CharacterSet.whitespacesAndNewlines.contains($1) ? 0 : 1) }324 guard n > 0 else { continue }325 let cacheKey = "\(p.style)\u{1}\(r.charStyle ?? "")\u{1}\(r.props.fontFamily ?? "")\u{1}\(r.props.fontSize.map { String($0) } ?? "")\u{1}\(r.props.color?.hexString ?? "")"326 let c: ResolvedChar327 if let cached = charCache[cacheKey] { c = cached } else {328 c = doc.styles.charProps(paraStyle: p.style, charStyle: r.charStyle, direct: CharProps(fontFamily: r.props.fontFamily, fontSize: r.props.fontSize, color: r.props.color))329 charCache[cacheKey] = c330 }331 total += n332 fonts[c.fontFamily, default: 0] += n333 sizes[format(c.fontSize) + " pt", default: 0] += n334 colours["#" + c.color.hexString, default: 0] += n335 }336 func uniform(_ d: [String: Int]) -> String? {337 guard total > 0, let best = d.max(by: { ($0.value, $1.key) < ($1.value, $0.key) }) else { return nil }338 return Double(best.value) / Double(total) >= options.formattingUniformShare ? best.key : nil339 }340 let para = doc.styles.paraProps(style: p.style, direct: p.props)341 let spacing: String342 switch para.lineSpacing {343 case .multiple(let m): spacing = "×" + String(format: "%.2f", m)344 case .exact(let v): spacing = "= \(format(v)) pt"345 case .atLeast(let v): spacing = "≥ \(format(v)) pt"346 }347 let values: [String?] = [uniform(fonts), uniform(sizes), uniform(colours), para.alignment.rawValue, format(para.indentLeft) + " pt",348 format(para.firstLineIndent) + " pt", spacing]349 let key = "\(p.style)\u{1}\(p.list == nil ? "" : "list")\u{1}\(ref.path.cell == nil ? "" : "cell")"350 if groups[key] == nil { groupOrder.append(key) }351 groups[key, default: []].append(Sample(ref: ref, values: values))352 }353 for key in groupOrder {354 let samples = groups[key]!355 guard samples.count >= options.formattingMinGroup else { continue }356 var notes = [[String]](repeating: [], count: samples.count)357 for a in attributes.indices {358 var tally: [String: Int] = [:]359 var counted = 0360 for s in samples { if let v = s.values[a] { tally[v, default: 0] += 1; counted += 1 } }361 guard counted >= options.formattingMinGroup, let dominant = tally.max(by: { ($0.value, $1.key) < ($1.value, $0.key) }) else { continue }362 guard dominant.value < counted, Double(dominant.value) / Double(counted) >= options.formattingDominance else { continue }363 for (i, s) in samples.enumerated() {364 guard let v = s.values[a], v != dominant.key else { continue }365 notes[i].append(t("\(attributes[a]) \(v), where \(dominant.value) of \(counted) paragraphs use \(dominant.key)",366 "\(attributes[a]) \(v), alors que \(dominant.value) paragraphes sur \(counted) utilisent \(dominant.key)"))367 }368 }369 for (i, s) in samples.enumerated() where !notes[i].isEmpty {370 let style = doc.styles.style(s.ref.paragraph.style)?.name ?? s.ref.paragraph.style371 add(.inconsistentFormatting, s.ref.paragraph.id, .info,372 evidence: t("\(quote(Scan.excerpt(s.ref.paragraph, limit: 70))) (style \(style)): ", "\(quote(Scan.excerpt(s.ref.paragraph, limit: 70))) (style \(style)) : ")373 + notes[i].joined(separator: "; ") + ".",374 location: location(s.ref))375 }376 }377 }378379 private func format(_ v: Double) -> String { v == v.rounded() ? String(Int(v)) : String(format: "%.1f", v) }380381 // MARK: Review state382383 private mutating func comments() {384 guard doc.comments.contains(where: { !$0.resolved }) else { return }385 var anchors: [String: ParagraphRef] = [:]386 var anchoredText: [String: String] = [:]387 for ref in refs {388 for r in ref.paragraph.runs where !r.comments.isEmpty {389 for id in r.comments {390 if anchors[id] == nil { anchors[id] = ref }391 if !r.isDeleted && r.inline == nil { anchoredText[id, default: ""] += r.text }392 }393 }394 }395 for c in doc.comments where !c.resolved {396 let anchor = anchors[c.id]397 var evidence = t("\(c.author): \(quote(Scan.short(c.text, limit: 140)))", "\(c.author) : \(quote(Scan.short(c.text, limit: 140)))")398 if !c.replies.isEmpty { evidence += t(" (\(c.replies.count) repl\(c.replies.count == 1 ? "y" : "ies"))", " (\(c.replies.count) réponse\(c.replies.count == 1 ? "" : "s"))") }399 if let text = anchoredText[c.id], !text.isEmpty { evidence += t(", on \(quote(Scan.short(text, limit: 80)))", ", sur \(quote(Scan.short(text, limit: 80)))") }400 else if anchor == nil { evidence += t(" — not anchored to any text", " — ancré à aucun texte") }401 add(.unresolvedComment, c.id, .info, evidence: evidence + ".", location: anchor.map { location($0) } ?? AuditLocation())402 }403 }404405 private mutating func trackedChanges() {406 var insertions: Set<String> = [], deletions: Set<String> = [], formats: Set<String> = [], authors: Set<String> = []407 var marks = 0, paragraphs = 0408 var first: ParagraphRef?409 for ref in refs where ref.paragraph.hasTrackedChanges {410 paragraphs += 1411 if first == nil { first = ref }412 if let m = ref.paragraph.markRevision { marks += 1; authors.insert(m.author) }413 for r in ref.paragraph.runs {414 if let rev = r.revision {415 authors.insert(rev.author)416 if rev.kind == .insertion { insertions.insert(rev.id) } else { deletions.insert(rev.id) }417 }418 if let f = r.formatRevision { formats.insert(f.id); authors.insert(f.author) }419 }420 }421 guard let first else { return }422 let who = authors.sorted().joined(separator: ", ")423 add(.pendingTrackedChange, "document", .warning,424 evidence: t("\(insertions.count) insertion(s), \(deletions.count) deletion(s), \(formats.count) formatting change(s) and \(marks) paragraph mark(s) in \(paragraphs) paragraph(s), by \(who). First: \(quote(Scan.short(first.paragraph.plainText.replacingOccurrences(of: objectReplacementCharacter, with: ""), limit: 90))).",425 "\(insertions.count) insertion(s), \(deletions.count) suppression(s), \(formats.count) modification(s) de mise en forme et \(marks) marque(s) de paragraphe dans \(paragraphs) paragraphe(s), par \(who). Première : \(quote(Scan.short(first.paragraph.plainText.replacingOccurrences(of: objectReplacementCharacter, with: ""), limit: 90)))."),426 location: location(first))427 }428429 private mutating func citations(_ incomplete: ((BibEntry) -> [String])?) {430 var uses: [String: (count: Int, first: ParagraphRef)] = [:]431 var order: [String] = []432 for ref in refs {433 for r in ref.paragraph.runs where !r.isDeleted {434 guard case .citation(let c)? = r.inline else { continue }435 for item in c.items {436 if let u = uses[item.key] { uses[item.key] = (u.count + 1, u.first) } else { uses[item.key] = (1, ref); order.append(item.key) }437 }438 }439 }440 let known = Set(doc.bibliography.map(\.key))441 if options.enabled.contains(.missingBibliographyEntry) {442 for key in order where !known.contains(key) {443 let u = uses[key]!444 add(.missingBibliographyEntry, key, .error,445 evidence: t("Key \(quote(key)) is cited \(u.count) time(s) and is not among the \(known.count) entries of the reference list. First citation in: \(quote(Scan.excerpt(u.first.paragraph, limit: 90))).",446 "La clé \(quote(key)) est citée \(u.count) fois et ne figure pas parmi les \(known.count) entrées de la liste de références. Première citation dans : \(quote(Scan.excerpt(u.first.paragraph, limit: 90)))."),447 location: location(u.first))448 }449 }450 if options.enabled.contains(.orphanedCitation), let bi = doc.body.firstIndex(where: { if case .bibliography = $0 { return true } else { return false } }) {451 let orphans = doc.bibliography.filter { uses[$0.key] == nil }452 if !orphans.isEmpty {453 let list = orphans.prefix(10).map { e in e.title.isEmpty ? e.key : "\(e.key) (\(Scan.short(e.title, limit: 50)))" }.joined(separator: "; ")454 let more = orphans.count > 10 ? t(" and \(orphans.count - 10) more", " et \(orphans.count - 10) autres") : ""455 add(.orphanedCitation, "document", .info,456 evidence: t("\(orphans.count) of \(doc.bibliography.count) entries are never cited: \(list)\(more).", "\(orphans.count) entrées sur \(doc.bibliography.count) ne sont jamais citées : \(list)\(more)."),457 location: blockLocation(bi, excerpt: t("[bibliography]", "[bibliographie]")))458 }459 }460 if options.enabled.contains(.incompleteReference), let incomplete {461 for entry in doc.bibliography {462 guard let u = uses[entry.key] else { continue }463 let missing = incomplete(entry)464 guard !missing.isEmpty else { continue }465 add(.incompleteReference, entry.key, .warning,466 evidence: t("Reference \(quote(entry.key)) (\(entry.type)\(entry.title.isEmpty ? "" : ", " + quote(Scan.short(entry.title, limit: 60)))) lacks: \(missing.joined(separator: ", ")).",467 "Il manque à la référence \(quote(entry.key)) (\(entry.type)\(entry.title.isEmpty ? "" : ", " + quote(Scan.short(entry.title, limit: 60)))) : \(missing.joined(separator: ", "))."),468 location: location(u.first))469 }470 }471 }472473 // MARK: Pages474475 private mutating func pageBreaks() {476 let body = doc.body477 func isEmptyParagraph(_ b: Block) -> Bool {478 if case .paragraph(let p) = b { return p.runs.allSatisfy { $0.isDeleted || ($0.inline == nil && $0.text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty) } }479 return false480 }481 func isPageBreak(_ b: Block) -> Bool { if case .pageBreak(let br) = b { return br.kind == .page } else { return false } }482 for (bi, block) in body.enumerated() where isPageBreak(block) {483 var next = bi + 1484 while next < body.count && isEmptyParagraph(body[next]) { next += 1 }485 var prev = bi - 1486 while prev >= 0 && isEmptyParagraph(body[prev]) { prev -= 1 }487 let here = blockLocation(bi, excerpt: t("[page break]", "[saut de page]"))488 if next >= body.count {489 add(.unusualPageBreak, "\(block.id)/end", .info,490 evidence: t("The page break at block \(bi + 1) is followed by no content: the document ends on an empty page.",491 "Le saut de page du bloc \(bi + 1) n'est suivi d'aucun contenu : le document se termine par une page vide."), location: here)492 continue493 }494 var blank = false495 switch body[next] {496 case .pageBreak(let br): blank = br.kind == .page497 case .sectionBreak(let s): blank = s.kind != .continuous498 case .paragraph(let p): blank = doc.styles.paraProps(style: p.style, direct: p.props).pageBreakBefore499 default: break500 }501 if blank {502 add(.unusualPageBreak, "\(block.id)/blank", .warning,503 evidence: t("The page break at block \(bi + 1) is directly followed by another break at block \(next + 1), with no content in between: a blank page.",504 "Le saut de page du bloc \(bi + 1) est suivi directement d'un autre saut au bloc \(next + 1), sans contenu entre les deux : une page blanche."), location: here)505 continue506 }507 if prev < 0 {508 add(.unusualPageBreak, "\(block.id)/start", .info,509 evidence: t("The document starts with a page break (block \(bi + 1)): its first page is empty.", "Le document commence par un saut de page (bloc \(bi + 1)) : sa première page est vide."),510 location: here)511 } else if case .paragraph(let p) = body[prev], levels.level(p) > 0 {512 add(.unusualPageBreak, "\(block.id)/heading", .warning,513 evidence: t("The page break at block \(bi + 1) comes right after the heading \(quote(Scan.excerpt(p, limit: 70))): the heading is left alone at the bottom of its page.",514 "Le saut de page du bloc \(bi + 1) suit immédiatement le titre \(quote(Scan.excerpt(p, limit: 70))) : le titre reste seul au bas de sa page."), location: here)515 }516 }517 guard let layout else { return }518 for page in Set(layout.nearlyEmptyPages).sorted() where page >= 1 && page <= max(layout.pageCount, 1) {519 // The first body block that starts on the page, when known.520 var first: Int?521 for (bi, b) in body.enumerated() where layout.pageOfBlock[b.id] == page { first = bi; break }522 var loc = first.map { blockLocation($0, excerpt: Scan.short(excerptOfBlock($0))) } ?? AuditLocation()523 loc.page = page524 add(.unusualPageBreak, "page/\(page)", page == layout.pageCount ? .info : .warning,525 evidence: t("Page \(page) of \(layout.pageCount) is almost empty.", "La page \(page) sur \(layout.pageCount) est presque vide."), location: loc)526 }527 }528529 private func excerptOfBlock(_ index: Int) -> String {530 switch doc.body[index] {531 case .paragraph(let p): return Scan.excerpt(p)532 case .table(let tb): return tb.rows.first.map { $0.cells.map(\.plainText).joined(separator: " | ") } ?? ""533 default: return ""534 }535 }536537 private mutating func overflowingTables() {538 var reported: Set<String> = []539 var section = 0540 let setups = doc.sectionSetups541 for (bi, block) in doc.body.enumerated() {542 if case .sectionBreak = block { section += 1; continue }543 guard case .table(let tb) = block else { continue }544 let setup = setups[min(section, setups.count - 1)]545 let available = setup.columns > 1 ? setup.columnWidth : setup.contentWidth546 if tb.totalWidth > available + 1 {547 reported.insert(tb.id)548 add(.overflowingTable, tb.id, .warning,549 evidence: t("The table at block \(bi + 1) is \(format(tb.totalWidth)) pt wide (\(tb.columnCount) columns); the text area is \(format(available)) pt wide: it overflows by \(format(tb.totalWidth - available)) pt.",550 "Le tableau du bloc \(bi + 1) mesure \(format(tb.totalWidth)) pt de large (\(tb.columnCount) colonnes) ; la zone de texte mesure \(format(available)) pt : il dépasse de \(format(tb.totalWidth - available)) pt."),551 location: blockLocation(bi, excerpt: Scan.short(excerptOfBlock(bi))))552 }553 }554 guard let layout else { return }555 for id in layout.overflowingTableIDs where !reported.contains(id) {556 guard let bi = doc.body.firstIndex(where: { $0.id == id }), case .table(let tb) = doc.body[bi] else { continue }557 reported.insert(id)558 add(.overflowingTable, id, .warning,559 evidence: t("The layout reports that the table at block \(bi + 1) (\(tb.rows.count) rows × \(tb.columnCount) columns, \(format(tb.totalWidth)) pt) does not fit in the text area.",560 "La mise en page signale que le tableau du bloc \(bi + 1) (\(tb.rows.count) lignes × \(tb.columnCount) colonnes, \(format(tb.totalWidth)) pt) ne tient pas dans la zone de texte."),561 location: blockLocation(bi, excerpt: Scan.short(excerptOfBlock(bi))))562 }563 }564565 private mutating func pageNumbers() {566 if let layout {567 guard layout.pageCount >= 2 else { return }568 let missing = Set(layout.pagesWithoutPageNumber).filter { $0 >= 1 && $0 <= layout.pageCount }.sorted()569 // A cover page without number is ordinary.570 guard !missing.isEmpty, missing != [1] else { return }571 let list = missing.prefix(12).map(String.init).joined(separator: ", ") + (missing.count > 12 ? "…" : "")572 add(.missingPageNumbers, "document", .warning,573 evidence: t("\(missing.count) of \(layout.pageCount) pages show no page number: \(list).", "\(missing.count) pages sur \(layout.pageCount) n'affichent aucun numéro : \(list)."),574 location: AuditLocation(page: missing.first))575 return576 }577 // Without pagination: a long document whose headers and footers hold no page number field at all.578 let words = bodyWordCount579 guard words >= options.pageNumberMinWords else { return }580 var hasField = false581 for ref in refs {582 switch ref.story {583 case .header, .footer:584 for r in ref.paragraph.runs where !r.isDeleted { if case .field(.pageNumber)? = r.inline { hasField = true } }585 default: break586 }587 }588 guard !hasField else { return }589 add(.missingPageNumbers, "document", .info,590 evidence: t("\(words) words (threshold: \(options.pageNumberMinWords)) and no page number field in any header or footer of the \(doc.sectionSetups.count) section(s).",591 "\(words) mots (seuil : \(options.pageNumberMinWords)) et aucun champ de numéro de page dans les en-têtes et pieds de page des \(doc.sectionSetups.count) section(s)."),592 location: AuditLocation())593 }594595 // MARK: Language596597 private mutating func acronyms() {598 for a in ResearchAssistant.undefinedAcronyms(in: doc, known: options.knownAcronyms) {599 let p = doc.blocks(in: a.firstUse.story).paragraph(at: a.firstUse.path)600 add(.undefinedAcronym, a.acronym, .info,601 evidence: t("\(quote(a.acronym)) is used \(a.count) time(s) and never spelled out. First use: \(quote(a.firstUse.context)).",602 "\(quote(a.acronym)) est employé \(a.count) fois sans jamais être développé. Première occurrence : \(quote(a.firstUse.context))."),603 location: location(a.firstUse.story, a.firstUse.path, p, excerpt: a.firstUse.context))604 }605 }606607 private mutating func unreferencedCaptions() {608 for c in ResearchAssistant.unreferencedCaptions(in: doc) {609 let label = Scan.folded(c.label)610 let check: AuditCheck611 if AuditRun.figureLabels.contains(label) { check = .unreferencedFigure } else if AuditRun.tableLabels.contains(label) { check = .unreferencedTable } else { continue }612 guard options.enabled.contains(check) else { continue }613 add(check, c.paragraphID, .info,614 evidence: t("\(quote(Scan.short(c.text, limit: 100))) (\(c.label) \(c.number), block \(c.blockIndex + 1)) is the target of no cross-reference and “\(c.label) \(c.number)” is not mentioned in the text.",615 "\(quote(Scan.short(c.text, limit: 100))) (\(c.label) \(c.number), bloc \(c.blockIndex + 1)) n'est la cible d'aucun renvoi et « \(c.label) \(c.number) » n'est pas mentionné dans le texte."),616 location: blockLocation(c.blockIndex, excerpt: Scan.short(c.text)))617 }618 }619620 private mutating func repeatedWording() {621 let o = ResearchAssistant.RepetitionOptions(window: options.repetitionWindow, minCount: options.repetitionMinCount, phraseWindow: options.phraseWindow,622 maxFindings: options.maxRepetitionFindings)623 for r in ResearchAssistant.repeatedWording(in: doc, language: options.language ?? doc.meta.language, options: o) {624 guard let first = r.occurrences.first else { continue }625 let p = doc.body.paragraph(at: first.path)626 let evidence: String627 switch r.kind {628 case .word:629 evidence = t("The word \(quote(r.text)) occurs \(r.count) times within \(r.span) words, starting at: \(quote(first.context)).",630 "Le mot \(quote(r.text)) revient \(r.count) fois en \(r.span) mots, à partir de : \(quote(first.context)).")631 case .phrase:632 evidence = t("The phrase \(quote(r.text)) occurs \(r.count) times within \(r.span) words, starting at: \(quote(first.context)).",633 "L'expression \(quote(r.text)) revient \(r.count) fois en \(r.span) mots, à partir de : \(quote(first.context)).")634 }635 add(.repeatedWording, r.id, .info, evidence: evidence, location: location(.body, first.path, p, excerpt: first.context))636 }637 }638639 private mutating func sentencesAndSpaces() {640 let spaces = try? NSRegularExpression(pattern: "(?<=[^\\s\\uFFFC]) {2,}(?=[^\\s\\uFFFC])")641 for ref in refs {642 let p = ref.paragraph643 if p.style == StyleID.code { continue }644 let text = Scan.maskedText(p)645 let ns = text as NSString646 guard ns.length >= 3 else { continue }647 if options.enabled.contains(.doubleSpaces), let spaces, text.contains(" ") {648 let matches = spaces.matches(in: text, range: NSRange(location: 0, length: ns.length))649 if let first = matches.first {650 let range = first.range.location..<(first.range.location + first.range.length)651 let shown = Scan.context(text, around: range, radius: 25).replacingOccurrences(of: " ", with: "·")652 add(.doubleSpaces, p.id, .info,653 evidence: t("\(matches.count) run(s) of consecutive spaces in the paragraph; the first (\(first.range.length) spaces, shown as ·): \(quote(shown)).",654 "\(matches.count) suite(s) d'espaces consécutives dans le paragraphe ; la première (\(first.range.length) espaces, affichées ·) : \(quote(shown))."),655 location: location(ref))656 }657 }658 guard options.enabled.contains(.longSentence) else { continue }659 switch ref.story { case .header, .footer: continue; default: break }660 if levels.level(p) > 0 || Scan.wordCount(text) <= options.longSentenceWords { continue }661 for s in Scan.sentenceRanges(ns) {662 let words = Scan.wordRanges(ns, in: s).count663 guard words > options.longSentenceWords else { continue }664 let sentence = ns.substring(with: s).replacingOccurrences(of: objectReplacementCharacter, with: "").trimmingCharacters(in: .whitespacesAndNewlines)665 add(.longSentence, "\(p.id)/\(s.location)", .info,666 evidence: t("\(words) words (threshold: \(options.longSentenceWords)): \(quote(Scan.short(sentence, limit: 160))).",667 "\(words) mots (seuil : \(options.longSentenceWords)) : \(quote(Scan.short(sentence, limit: 160)))."),668 location: location(ref, excerpt: Scan.short(sentence)))669 }670 }671 }672673 private mutating func metadata() {674 var missing: [String] = []675 let m = doc.meta676 for field in AuditOptions.MetadataField.allCases where options.requiredMetadata.contains(field) {677 switch field {678 case .title: if m.title.trimmingCharacters(in: .whitespaces).isEmpty { missing.append(t("title", "titre")) }679 case .author: if m.author.trimmingCharacters(in: .whitespaces).isEmpty { missing.append(t("author", "auteur")) }680 case .subject: if m.subject.trimmingCharacters(in: .whitespaces).isEmpty { missing.append(t("subject", "sujet")) }681 case .keywords: if m.keywords.allSatisfy({ $0.trimmingCharacters(in: .whitespaces).isEmpty }) { missing.append(t("keywords", "mots-clés")) }682 case .language: if m.language.trimmingCharacters(in: .whitespaces).isEmpty { missing.append(t("language", "langue")) }683 }684 }685 guard !missing.isEmpty else { return }686 add(.missingMetadata, "document", .info,687 evidence: t("Empty properties: \(missing.joined(separator: ", ")).", "Propriétés vides : \(missing.joined(separator: ", "))."), location: AuditLocation())688 }689}690