Quality auditor and research assistant (DocAudit)
Auditor
DocumentAuditor.audit(_:layout:options:incompleteReference:) runs the enabled checks and returns [AuditFinding].
Every finding has a stable id (check + paragraph id, key or name), a severity, a title, an explanation, evidence taken from the
document (quoted text, ids, counts), a suggestion and a location (story, path, paragraph id, page when layout facts are given;
path == nil for a finding about the whole document). Findings are sorted by position, then by check; the same input gives the same
output. Titles, explanations and suggestions exist in English and French (AuditTexts.table), chosen by
options.language ?? doc.meta.language (French when it starts with "fr").
LayoutFacts (page count, page of each block, overflowing tables, nearly empty pages, pages without number) comes from the layout
engine after pagination. DocumentAuditor.reportDocument(_:for:) builds a formatted report (summary table per check and severity,
findings grouped by severity) in the document's language.
Checks and thresholds
| Check | Fires when | Does not fire when |
|---|---|---|
missingHeadings |
≥ 1 500 words (longDocumentWords) and no heading |
shorter text, or one heading |
headingHierarchy |
a heading is more than one level below the previous one; or the first heading is deeper than the top level used | going back up; a document that only uses level 2 and below |
emptyHeading |
heading-style paragraph without text or object | empty body paragraph |
duplicateHeading |
same text (case, accents, spacing ignored), same level, same parent | same title under different parents |
brokenCrossReference |
CrossRef whose target fails Numbering.targetExists; #bookmark link without bookmark |
external links |
missingFigureCaption |
paragraph holding only image(s), with no caption paragraph carrying a figure sequence field just before or after the group of images | image inside a sentence; images sharing one caption |
missingTableCaption |
table ≥ 2 × 2 with no adjacent caption carrying a table sequence; warning when requireTableCaptions or another table has a caption, information otherwise |
one-row or one-column layout tables |
missingAltText |
image with empty alternative text | — |
inconsistentFormatting |
see below | see below |
unresolvedComment |
one per unresolved comment | resolved comments |
pendingTrackedChange |
one finding for the document, with counts and authors | — |
missingBibliographyEntry |
cited key absent from doc.bibliography (one per key) |
— |
orphanedCitation |
entries never cited, when a bibliography block exists (one finding listing them) | no bibliography block |
incompleteReference |
the injected closure returns missing fields for a cited entry | no closure; uncited entries |
unusualPageBreak |
two page breaks with nothing between; break at the end or start of the document; break right after a heading; with layout facts, each nearly empty page | a break between two texts or before a heading; column breaks |
overflowingTable |
table wider than the text area of its section by more than 1 pt; tables listed by the layout | — |
missingPageNumbers |
with layout: ≥ 2 pages and pages without number other than page 1 alone; without layout: ≥ 1 000 words and no page-number field in any header or footer | a single page; only the cover unnumbered |
undefinedAcronym |
see the research assistant | — |
unreferencedFigure, unreferencedTable |
caption that no cross-reference targets and that the text never names ("Figure 3", "Fig. 3", "Tableau 2") | — |
repeatedWording |
see the research assistant (window 100 words, 6 occurrences; phrase window 250 words) | — |
longSentence |
sentence with more than 40 words (longSentenceWords; 50 academic, 35 business) |
headings, code, headers and footers |
doubleSpaces |
two or more spaces between two visible characters (one finding per paragraph) | code-style paragraphs; trailing spaces |
missingMetadata |
a required property is empty (title, author, language; keywords in the academic profile) | — |
At most maxFindingsPerCheck (100) findings are kept per check; one extra finding gives the number left out.
inconsistentFormatting
Body paragraphs are grouped by style (lists and table cells apart). Seven attributes are compared: font, font size, text colour, alignment, left indent, first-line indent, line spacing — as resolved values. A paragraph is reported only when all of this holds:
- its group has at least 8 non-empty paragraphs (
formattingMinGroup); - at least 80 % of them share one value (
formattingDominance); - the paragraph has another value;
- for font, size and colour, that value covers at least 90 % of the paragraph's characters (
formattingUniformShare).
Bold, italic, underline and highlighting are never compared, so emphasis, a larger word or a coloured phrase is not a finding.
Profiles
AuditOptions() enables every check. .academic: every check, captions required on tables, 50-word sentences, keywords expected.
.business: no bibliography, reference or repetition checks, 35-word sentences. .minimal: broken references, missing bibliography
entries, comments, tracked changes, empty headings, overflowing tables, alternative text.
Research assistant
Everything is rule-based and quotes the document; nothing is generated.
search(_:in:documentName:options:)andsearch(_:across:options:): body, tables, notes, headers and footers; case- and diacritic-insensitive by default; whole word; ICU regular expressions. AHitgives the story, the paragraph path, the UTF-16 range inParagraph.plainText, a context and the heading trail. Text deleted by a tracked change is not searched.undefinedAcronyms(in:): words of 2–8 capitals and digits (optional plural "s") that are never expanded. Roman numerals, a built-in list of common acronyms, the caller's list and text typed in capitals are ignored. Definitions recognised anywhere in the document: "long form (ACR)", "long form (ci-après « ACR »)", "ACR (long form)", "ACR stands for / means / signifie / désigne / : …". The letters of the acronym must be readable in order in the long form, starting on a word initial, at least half of them on word initials.citedPassages(in:): each sentence containing a citation, with its keys; a citation placed after the final period belongs to that sentence.unreferencedCaptions(in:),outline(of:).repeatedWording(in:language:): content words grouped by lemma (NLTagger, falling back to the lower-cased word) occurring at least 6 times within 100 consecutive words; phrases of four words or more repeated within 250 words (three-word phrases need three occurrences), extended to their full length. Stop words (English and French lists) never count; headings and code are excluded.actionItems(in:): paragraphs with a marker from a fixed list (TODO, FIXME, "à faire", "must", "doit", "action:", "next steps:", "prochaines étapes 😊 or an unchecked box ("[ ]", "☐"). Rule-based, not AI.
Limits
- Regular-expression search is diacritic-insensitive only for text whose length is unchanged by removing diacritics (precomposed characters); decomposed text is matched as written.
- A phrase interrupted by text marked as deleted is not found by search.
- Sentence segmentation is Foundation's; abbreviations can split a sentence early.
- Repeated-wording results depend on the lemma models installed with macOS.
- Measured by
threeThousandParagraphAudit(debug build, Apple silicon): 3 000 paragraphs with every check in about 1.2 s.