Repository Public
1<!--2ORIX Docs3File: docs/architecture/audit.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Quality auditor and research assistant (`DocAudit`)89## Auditor1011`DocumentAuditor.audit(_:layout:options:incompleteReference:)` runs the enabled checks and returns `[AuditFinding]`.12Every finding has a stable `id` (check + paragraph id, key or name), a severity, a title, an explanation, **evidence taken from the13document** (quoted text, ids, counts), a suggestion and a location (story, path, paragraph id, page when layout facts are given;14`path == nil` for a finding about the whole document). Findings are sorted by position, then by check; the same input gives the same15output. Titles, explanations and suggestions exist in English and French (`AuditTexts.table`), chosen by16`options.language ?? doc.meta.language` (French when it starts with "fr").1718`LayoutFacts` (page count, page of each block, overflowing tables, nearly empty pages, pages without number) comes from the layout19engine after pagination. `DocumentAuditor.reportDocument(_:for:)` builds a formatted report (summary table per check and severity,20findings grouped by severity) in the document's language.2122### Checks and thresholds2324| Check | Fires when | Does not fire when |25|---|---|---|26| `missingHeadings` | ≥ 1 500 words (`longDocumentWords`) and no heading | shorter text, or one heading |27| `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 |28| `emptyHeading` | heading-style paragraph without text or object | empty body paragraph |29| `duplicateHeading` | same text (case, accents, spacing ignored), same level, same parent | same title under different parents |30| `brokenCrossReference` | `CrossRef` whose target fails `Numbering.targetExists`; `#bookmark` link without bookmark | external links |31| `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 |32| `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 |33| `missingAltText` | image with empty alternative text | — |34| `inconsistentFormatting` | see below | see below |35| `unresolvedComment` | one per unresolved comment | resolved comments |36| `pendingTrackedChange` | one finding for the document, with counts and authors | — |37| `missingBibliographyEntry` | cited key absent from `doc.bibliography` (one per key) | — |38| `orphanedCitation` | entries never cited, when a bibliography block exists (one finding listing them) | no bibliography block |39| `incompleteReference` | the injected closure returns missing fields for a cited entry | no closure; uncited entries |40| `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 |41| `overflowingTable` | table wider than the text area of its section by more than 1 pt; tables listed by the layout | — |42| `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 |43| `undefinedAcronym` | see the research assistant | — |44| `unreferencedFigure`, `unreferencedTable` | caption that no cross-reference targets and that the text never names ("Figure 3", "Fig. 3", "Tableau 2") | — |45| `repeatedWording` | see the research assistant (window 100 words, 6 occurrences; phrase window 250 words) | — |46| `longSentence` | sentence with more than 40 words (`longSentenceWords`; 50 academic, 35 business) | headings, code, headers and footers |47| `doubleSpaces` | two or more spaces between two visible characters (one finding per paragraph) | code-style paragraphs; trailing spaces |48| `missingMetadata` | a required property is empty (title, author, language; keywords in the academic profile) | — |4950At most `maxFindingsPerCheck` (100) findings are kept per check; one extra finding gives the number left out.5152### `inconsistentFormatting`5354Body paragraphs are grouped by style (lists and table cells apart). Seven attributes are compared: font, font size, text colour,55alignment, left indent, first-line indent, line spacing — as resolved values. A paragraph is reported only when all of this holds:5657* its group has at least **8** non-empty paragraphs (`formattingMinGroup`);58* at least **80 %** of them share one value (`formattingDominance`);59* the paragraph has another value;60* for font, size and colour, that value covers at least **90 %** of the paragraph's characters (`formattingUniformShare`).6162Bold, italic, underline and highlighting are never compared, so emphasis, a larger word or a coloured phrase is not a finding.6364### Profiles6566`AuditOptions()` enables every check. `.academic`: every check, captions required on tables, 50-word sentences, keywords expected.67`.business`: no bibliography, reference or repetition checks, 35-word sentences. `.minimal`: broken references, missing bibliography68entries, comments, tracked changes, empty headings, overflowing tables, alternative text.6970## Research assistant7172Everything is rule-based and quotes the document; nothing is generated.7374* `search(_:in:documentName:options:)` and `search(_:across:options:)`: body, tables, notes, headers and footers; case- and75 diacritic-insensitive by default; whole word; ICU regular expressions. A `Hit` gives the story, the paragraph path, the UTF-16 range76 in `Paragraph.plainText`, a context and the heading trail. Text deleted by a tracked change is not searched.77* `undefinedAcronyms(in:)`: words of 2–8 capitals and digits (optional plural "s") that are never expanded. Roman numerals, a built-in78 list of common acronyms, the caller's list and text typed in capitals are ignored. Definitions recognised anywhere in the document:79 "long form (ACR)", "long form (ci-après « ACR »)", "ACR (long form)", "ACR stands for / means / signifie / désigne / : …". The80 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.81* `citedPassages(in:)`: each sentence containing a citation, with its keys; a citation placed after the final period belongs to that sentence.82* `unreferencedCaptions(in:)`, `outline(of:)`.83* `repeatedWording(in:language:)`: content words grouped by lemma (`NLTagger`, falling back to the lower-cased word) occurring at84 least 6 times within 100 consecutive words; phrases of four words or more repeated within 250 words (three-word phrases need three85 occurrences), extended to their full length. Stop words (English and French lists) never count; headings and code are excluded.86* `actionItems(in:)`: paragraphs with a marker from a fixed list (TODO, FIXME, "à faire", "must", "doit", "action:", "next steps:",87 "prochaines étapes :") or an unchecked box ("[ ]", "☐"). Rule-based, not AI.8889## Limits9091* Regular-expression search is diacritic-insensitive only for text whose length is unchanged by removing diacritics (precomposed92 characters); decomposed text is matched as written.93* A phrase interrupted by text marked as deleted is not found by search.94* Sentence segmentation is Foundation's; abbreviations can split a sentence early.95* Repeated-wording results depend on the lemma models installed with macOS.96* Measured by `threeThousandParagraphAudit` (debug build, Apple silicon): 3 000 paragraphs with every check in about 1.2 s.97