SPB Git

Repository Public

audit.md 7.7 KB

# 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:) and search(_:across:options:): body, tables, notes, headers and footers; case- and diacritic-insensitive by default; whole word; ICU regular expressions. A Hit gives the story, the paragraph path, the UTF-16 range in Paragraph.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.
Files main
Menu

Theme