@json-to-office/jto-ops 4.0.0 → 4.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FontRuntimeOpts, ServicesConfig, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, ResolvedFont } from '@json-to-office/shared';
-import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis } from '@json-to-office/quality';
+import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis, QualityRulePack, QualityDiagnostic, QualityAnalyzeOptions } from '@json-to-office/quality';
 
 type FormatName = 'docx' | 'pptx';
 interface GeneratorOptions {
@@ -322,15 +322,30 @@ interface PdfTextWord {
     xMax: number;
     yMax: number;
 }
+/**
+ * One line as poppler's layout analysis grouped it (`-bbox-layout` only):
+ * its box plus the indices into `words` of the words on it.
+ */
+interface PdfTextLine {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+    words: number[];
+}
 /** One PDF page: its size in points plus every word poppler segmented. */
 interface PdfTextPage {
     widthPt: number;
     heightPt: number;
+    /** Every word in stream order, whichever mode produced the page. */
     words: PdfTextWord[];
+    /** Line grouping; empty for plain `-bbox` output, which groups nothing. */
+    lines: PdfTextLine[];
 }
 /**
- * Parse `pdftotext -bbox` output (XHTML with `<page>`/`<word>` elements).
- * Pure — feed it a captured document for tests, or the runner's stdout.
+ * Parse `pdftotext -bbox` or `-bbox-layout` output (XHTML with `<page>`,
+ * optionally `<line>`, and `<word>` elements). Pure — feed it a captured
+ * document for tests, or the runner's stdout.
  */
 declare function parsePdfTextBbox(bboxXml: string): PdfTextPage[];
 /** True when a `pdftotext` binary is reachable — lets harnesses skip early. */
@@ -338,11 +353,270 @@ declare function pdftotextAvailable(): Promise<boolean>;
 /**
  * Extract per-word text geometry from a PDF on disk. One pdftotext spawn,
  * output streamed through stdout — nothing else touches the filesystem.
+ * `layout: true` asks poppler for its line grouping too (`-bbox-layout`).
  */
 declare function extractPdfTextGeometry(pdfPath: string, options?: {
     timeoutMs?: number;
+    layout?: boolean;
 }): Promise<PdfTextPage[]>;
 
+/**
+ * Font names from a rendered PDF — the other half of substitution detection.
+ *
+ * `pdftotext -bbox` says where every word landed but not which face drew it.
+ * `pdffonts` (poppler, next to pdftotext) lists every font the PDF embeds or
+ * references; LibreOffice embeds the face it actually used, so a requested
+ * family that never appears in that list was substituted on the way.
+ *
+ * Names are PostScript-style: a subset tag (`BAAAAA+`), the family with
+ * spaces removed, and a style suffix (`-Bold`, `Medium-Regular`). Comparison
+ * therefore happens on a folded form — lowercase alphanumerics only — where
+ * "Space Grotesk" and `CAAAAA+SpaceGrotesk-Regular` meet as a prefix match.
+ */
+/** One font row as `pdffonts` prints it. */
+interface PdfFontInfo {
+    /** The name as printed, subset tag included. */
+    name: string;
+    /** The name without its subset tag: `DMSans-Regular`. */
+    baseName: string;
+    type: string;
+    embedded: boolean;
+}
+/**
+ * Parse `pdffonts` output. Pure; the header and rule lines are skipped and
+ * a row that does not fit the column layout is ignored rather than guessed.
+ */
+declare function parsePdfFonts(stdout: string): PdfFontInfo[];
+/**
+ * Whether a requested family is present among the rendered fonts. A family
+ * matches a PDF font whose folded base name starts with the folded family
+ * — `dmsans` against `dmsanslightregular` — so style suffixes never split
+ * one family into several.
+ */
+declare function familyRendered(family: string, fonts: readonly PdfFontInfo[]): boolean;
+/** True when a `pdffonts` binary is reachable. */
+declare function pdffontsAvailable(): Promise<boolean>;
+/** The fonts a PDF on disk carries. One spawn, stdout only. */
+declare function extractPdfFonts(pdfPath: string, options?: {
+    timeoutMs?: number;
+}): Promise<PdfFontInfo[]>;
+
+/**
+ * The rendered pass as a quality rule pack (#344).
+ *
+ * `draftRenderedFindings` measures; these rules are how the measurement
+ * enters the quality contract. Each rule owns one code, one description the
+ * design guide prints, and the defaults a profile or policy can move. All of
+ * them read a single `rendered/geometry` fact — the PDF's word boxes, its
+ * embedded fonts and the document's text inventory — and share one matching
+ * pass over it, memoised per fact, so eight rules cost one search.
+ */
+
+type RenderedRuleId = 'rendered/clip' | 'rendered/spill' | 'rendered/overlap' | 'rendered/text-missing' | 'rendered/font-substituted' | 'rendered/empty-page' | 'rendered/heading-stranded' | 'rendered/paragraph-split';
+declare const RENDERED_QUALITY_RULES: QualityRulePack;
+
+/**
+ * Locate authored text in rendered PDF geometry.
+ *
+ * Promoted from the ground-truth harness's sentinel search: fold both sides
+ * into lowercase alphanumerics (NFKC splits ligatures, punctuation and bullet
+ * glyphs drop out), concatenate every word fragment into one stream, and
+ * search that. Narrow boxes hard-wrap a word mid-word and letter-spaced text
+ * makes poppler emit per-cluster fragments; a per-word comparison loses both,
+ * a stream keeps them. A match must start where a fragment starts and end
+ * where one ends, so "page" never matches inside "homepage".
+ *
+ * The stream spans the whole document, not one page, so a paragraph that
+ * breaks across a page is still one match — which is exactly the case the
+ * widow and orphan checks need. Running heads and footers would interleave
+ * the two halves, so text that repeats by design is matched first, inside
+ * the top and bottom bands of each page, and its rows are removed from the
+ * stream before anything else is; a row of nothing but digits in those
+ * bands is a page number and goes with them.
+ *
+ * Fields, footnote marks and cross-references render a value the author
+ * never typed. The needle is cut at each of them into segments that must
+ * follow one another in the stream with at most a short gap between.
+ *
+ * Duplicate strings — "Total" in three tables — are why a search returns
+ * every occurrence. `assignInventory` resolves them by reading order: the
+ * inventory is walked in document order and the stream is in page order, so
+ * the next unclaimed occurrence at or after the previous claim is the one.
+ */
+
+/** Fold rendered and authored text into one comparable form. */
+declare function normalizeForMatch(value: string): string;
+/**
+ * Authored strings carry markup the page never shows: emphasis markers,
+ * link targets, and fields, footnote references and cross-references whose
+ * rendered value is unknowable here. The first two are dropped; the others
+ * become a `FIELD` mark that `needleSegments` splits on.
+ */
+declare function authoredTextForMatch(text: string): string;
+/** The part of a match that lies on one page, with its union box. */
+interface OccurrencePart {
+    pageIndex: number;
+    words: number[];
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+interface TextOccurrence {
+    /** Offset into the document stream, for ordering. */
+    at: number;
+    /** First and last page the match touches; equal unless it breaks across. */
+    pageIndex: number;
+    endPageIndex: number;
+    parts: OccurrencePart[];
+}
+/** What an inventory entry needs to be matched: its text, in reading order. */
+interface InventoryEntry {
+    path: string;
+    text: string;
+    /** Header/footer text repeats per page: every occurrence is legitimate. */
+    repeats?: boolean;
+    /**
+     * Painted by the renderer from other authored text — a contents entry —
+     * so it claims its occurrence when there is one and is `skipped`, never
+     * `missing`, when there is not.
+     */
+    optional?: boolean;
+}
+type MappingStatus = 'mapped' | 'ambiguous' | 'missing' | 'skipped';
+interface InventoryMatch<T extends InventoryEntry = InventoryEntry> {
+    entry: T;
+    needle: string;
+    status: MappingStatus;
+    /** One occurrence when mapped; every occurrence when the text repeats. */
+    occurrences: TextOccurrence[];
+    /**
+     * Set when only a leading part of the text rendered: the rest was cut
+     * off by a frame, a page edge or a box. Folded character counts.
+     */
+    partial?: {
+        matchedChars: number;
+        totalChars: number;
+    };
+}
+interface InventoryAssignment<T extends InventoryEntry> {
+    matches: InventoryMatch<T>[];
+    /** `pageIndex:word` keys of every word chrome claimed — whole rows. */
+    chromeWords: ReadonlySet<string>;
+}
+/**
+ * Attribute rendered occurrences to inventory entries.
+ *
+ * Repeating entries go first and claim their occurrences inside the page
+ * bands, one row each; rows of nothing but digits in those bands — page
+ * numbers — go with them. The rest are visited in document order over a
+ * stream without those words; each claims the first unclaimed occurrence at
+ * or after the previous claim, which is how "Total" in the second table
+ * finds the second "Total". An entry with no occurrence is `missing` —
+ * fully clipped, or never set — unless it is optional, and one whose every
+ * occurrence was already claimed is `ambiguous`.
+ */
+declare function assignInventory<T extends InventoryEntry>(pages: readonly PdfTextPage[], inventory: readonly T[]): InventoryAssignment<T>;
+
+/**
+ * The rendered-certainty pass (#344): findings from what LibreOffice
+ * actually laid out, mapped back to the pointers that authored them.
+ *
+ * Static rules predict; this pass measures. It reads per-word geometry from
+ * the preview PDF, the fonts the PDF embeds, and the document's authored
+ * text inventory, and reports the defects only ink can show: text past the
+ * page or its frame, words drawn over each other, text that never rendered
+ * (fully clipped, or set in a place poppler cannot read), faces substituted
+ * on the way, pages with nothing on them, headings stranded at a page foot
+ * and paragraphs split into a lone line.
+ *
+ * Every finding carries `certainty: 'rendered'` and an explicit mapping
+ * status. A defect whose words match no inventory entry is still reported,
+ * at the document root, as `unmapped` — an unmapped finding is a mapping
+ * gap to close, never a defect to hide.
+ *
+ * Pure: geometry and fonts are extracted by the caller (see
+ * `extractPdfTextGeometry`, `extractPdfFonts`), so every rule here is
+ * testable from captured fixtures with no converter on the host.
+ *
+ * The checks draft findings; the quality engine turns them into
+ * diagnostics. Each check is one rule of `RENDERED_QUALITY_RULES`, so a
+ * profile can switch one off or move its severity, a policy can suppress
+ * one at a pointer and a gate can make one blocking — the same levers every
+ * static rule answers to, applied to the pass that measures.
+ */
+
+/** One authored string the pass can match rendered words back to. */
+interface RenderedTextEntry extends InventoryEntry {
+    role: 'heading' | 'body' | 'list-item' | 'table-header' | 'table-cell' | 'statistic' | 'caption' | 'toc-entry' | 'chrome' | 'slide-text';
+    level?: number;
+    /** A declared box the text must fit: a docx frame, a pptx text box. */
+    box?: {
+        widthPt?: number;
+        heightPt?: number;
+    };
+}
+interface RequestedFont {
+    family: string;
+    /** Where the family was requested, when the document names it. */
+    path?: string;
+    /**
+     * The document supplied a source for the family (a file, a URL), so the
+     * preview should have had it and a substitution is the document's defect.
+     * Without one the family is a host font — Calibri on a Mac without Office
+     * — and the substitution says something about the preview, not the file.
+     */
+    declared?: boolean;
+}
+interface RenderedAnalysisInput {
+    format: 'docx' | 'pptx';
+    /** Renderer identity, for a profile that declares renderer targets. */
+    renderer?: string;
+    pages: readonly PdfTextPage[];
+    inventory: readonly RenderedTextEntry[];
+    /** Fonts the PDF carries; `undefined` when the host could not inspect them. */
+    fonts?: readonly PdfFontInfo[];
+    requestedFonts?: readonly RequestedFont[];
+}
+/** How a finding reached its pointer — always on `context.mapping`. */
+type RenderedMapping = 'mapped' | 'ambiguous' | 'unmapped';
+interface RenderedAnalysisSummary {
+    pages: number;
+    words: number;
+    /** Inventory entries by mapping outcome. */
+    inventory: Record<MappingStatus, number>;
+    /** Findings by mapping outcome, after suppressions. */
+    findings: Record<RenderedMapping, number>;
+    fonts?: {
+        requested: number;
+        substituted: number;
+    };
+    /** Findings a policy suppression removed. */
+    suppressed: number;
+    /** Whether a policy gate made any finding blocking. */
+    blocked: boolean;
+    /** Whether a policy `maxDiagnostics` budget cut the findings returned. */
+    truncated: boolean;
+    /** The quality profile the pass ran under, when one applied. */
+    profileId?: string;
+}
+interface RenderedAnalysis {
+    /** The pass's diagnostics, as the quality engine finalised them. */
+    findings: readonly QualityDiagnostic[];
+    summary: RenderedAnalysisSummary;
+    /** The engine's own account: evaluated rules, rule errors, truncation. */
+    analysis: QualityAnalysis;
+}
+/** Spill below this is sub-visual: renderer rounding, descender fuzz. */
+declare const VISIBLE_SPILL_PT = 2;
+/**
+ * Run the pass. Geometry, fonts and inventory become one `rendered/geometry`
+ * fact; the rendered rule pack reads it under the caller's profile and
+ * policy, so the findings come back suppressed, re-severed and gated the
+ * way `jto_validate`'s would.
+ */
+declare function analyzeRenderedDocument(input: RenderedAnalysisInput, options?: QualityAnalyzeOptions): RenderedAnalysis;
+
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
  * duration of one PDF conversion, then clean up.
@@ -534,4 +808,4 @@ declare function emitDiagnostic(text: string, tone?: DiagnosticTone): void;
  */
 declare const stderrDiagnosticSink: DiagnosticSink;
 
-export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, MacOSCoreTextStager, NoopFontStager, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, type RasterizerCacheStats, WindowsFontStager, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, extractPdfTextGeometry, getFontStager, getRasterizerCacheStats, parsePdfTextBbox, pdftotextAvailable, runWithDiagnosticSink, stderrDiagnosticSink };
+export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, type InventoryEntry, type InventoryMatch, MacOSCoreTextStager, type MappingStatus, NoopFontStager, type PdfFontInfo, type PdfTextLine, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, RENDERED_QUALITY_RULES, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, type RenderedRuleId, type RenderedTextEntry, type RequestedFont, type TextOccurrence, VISIBLE_SPILL_PT, WindowsFontStager, analyzeRenderedDocument, assignInventory, authoredTextForMatch, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, extractPdfFonts, extractPdfTextGeometry, familyRendered, getFontStager, getRasterizerCacheStats, normalizeForMatch, parsePdfFonts, parsePdfTextBbox, pdffontsAvailable, pdftotextAvailable, runWithDiagnosticSink, stderrDiagnosticSink };