SPB Git

Repository Public

DocumentAuditor.swift 44.0 KB 690 lines swift

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

Theme