@json-to-office/jto-ops 4.1.0 → 4.4.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, QualityDiagnostic } from '@json-to-office/quality';
+import { FontRuntimeOpts, ServicesConfig, GenerationWarning, RendererStatus, PptxBatchRasterizer, PptxRasterizer, JsonBlockDefinition, BlockSlot, ResolvedFont } from '@json-to-office/shared';
+import { QualityProfile, QualityPolicy, PreparedDocument, QualityAnalysis, QualityRulePack, QualityDiagnostic, QualityAnalyzeOptions } from '@json-to-office/quality';
 
 type FormatName = 'docx' | 'pptx';
 interface GeneratorOptions {
@@ -401,6 +401,20 @@ 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.
  *
@@ -456,12 +470,34 @@ interface TextOccurrence {
     endPageIndex: number;
     parts: OccurrencePart[];
 }
+/**
+ * Word indices in the order a reader takes them, decided from geometry
+ * rather than from the order poppler emitted them: poppler 24 lists a table
+ * row line by line across every cell, poppler 26 lists it cell by cell, and
+ * an authored string in a wrapped cell only survives the second.
+ *
+ * Rows are grouped by vertical overlap and split into fragments at gaps
+ * wider than half the line is tall. A row of two or more fragments opens a
+ * column block; the rows under it belong to the block while each of their
+ * fragments sits inside one column (a right-aligned cell's second line
+ * starts further right; a wrapped label's later lines are the only
+ * fragment of their row) and the rows stay a line apart. A block reads
+ * column by column, so a cell's lines come out together; a row of one
+ * fragment outside any block — prose — reads as it lies.
+ */
+declare function readingOrder(words: readonly PdfTextWord[]): number[];
 /** 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> {
@@ -493,8 +529,8 @@ interface InventoryAssignment<T extends InventoryEntry> {
  * 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 — and one whose every occurrence was already
- * claimed is `ambiguous`.
+ * 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>;
 
@@ -518,11 +554,17 @@ declare function assignInventory<T extends InventoryEntry>(pages: readonly PdfTe
  * 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' | 'chrome' | 'slide-text';
+    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?: {
@@ -544,6 +586,8 @@ interface RequestedFont {
 }
 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. */
@@ -557,21 +601,159 @@ interface RenderedAnalysisSummary {
     words: number;
     /** Inventory entries by mapping outcome. */
     inventory: Record<MappingStatus, number>;
-    /** Findings by mapping outcome. */
+    /** 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 {
-    findings: QualityDiagnostic[];
+    /** 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. */
-declare function analyzeRenderedDocument(input: RenderedAnalysisInput): RenderedAnalysis;
+/**
+ * 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;
+
+/**
+ * The block boundary matrix (#343, report portion): every JSON block
+ * definition a playground template embeds, invoked at the edges of its own
+ * slot schema — minimum and maximum cardinality, every string at its word
+ * budget, every figure at its widest — on each bundled theme, with the
+ * design fonts and with the fallback faces LibreOffice substitutes when a
+ * host lacks them, on A4 and on Letter.
+ *
+ * The generator is pure and reads nothing but the template it is handed:
+ * a definition gains coverage by being embedded, never by being listed here.
+ * What the suites do with a case — the static rules under the archetype's
+ * profile, the rendered pass over the LibreOffice PDF — is theirs; this
+ * module only says what a boundary document is.
+ *
+ * Two shapes come out. A *block case* is a small report — cover, running
+ * head, section opener — with one block at an edge in the body, so a
+ * finding names the block that caused it. A *report case* is the template's
+ * own document with every invocation at that edge, so the blocks meet each
+ * other the way they do in a real report. Both carry their definitions and
+ * dependencies inline, so nothing is resolved at render time.
+ */
+
+type Rec = Record<string, unknown>;
+type MatrixEdge = 'min' | 'max';
+type MatrixFont = 'design' | 'fallback';
+type MatrixCanvas = 'A4' | 'LETTER';
+interface BlockMatrixDefinition {
+    name: string;
+    /** The template the definition is embedded in, as the catalog names it. */
+    template: string;
+    /** Where inside that template: `/props/blocks/<name>`. */
+    pointer: string;
+    definition: JsonBlockDefinition;
+    /** The template's own first invocation, when it has one: the nominal fill. */
+    example?: Rec;
+}
+interface BlockMatrixCase {
+    id: string;
+    /** The block at its edge, or `report` for the whole template at that edge. */
+    block: string;
+    edge: MatrixEdge;
+    theme: string;
+    font: MatrixFont;
+    canvas: MatrixCanvas;
+    document: Rec;
+}
+interface BlockMatrixOptions {
+    themes: readonly string[];
+    fonts?: readonly MatrixFont[];
+    edges?: readonly MatrixEdge[];
+    canvases?: readonly MatrixCanvas[];
+    /** Whether the whole-template report cases are generated. Default true. */
+    report?: boolean;
+    /** Whether the per-block cases are generated. Default true. */
+    blocks?: boolean;
+    /**
+     * Slot roles the profile under test requires present, so `min` keeps them:
+     * the client-report profile's `takeaway` and `source`.
+     */
+    requiredRoles?: readonly string[];
+}
+interface CaseConditions {
+    font?: MatrixFont;
+    canvas?: MatrixCanvas;
+    requiredRoles?: readonly string[];
+}
+/**
+ * The face every LibreOffice ships with, bundled inside the application on
+ * each platform: what a design font degrades to when the host lacks it, and
+ * wider than Arial or Calibri, so a fit at these metrics is a fit anywhere.
+ * Only the roles a report paints are overridden: a family declared for a
+ * role nothing uses is never embedded, and the rendered pass would report
+ * it as substituted.
+ */
+declare const FALLBACK_FONTS: {
+    readonly heading: {
+        readonly family: "DejaVu Sans";
+    };
+    readonly body: {
+        readonly family: "DejaVu Sans";
+    };
+};
+/** A 4x2 PNG: an image with an aspect ratio, and no bytes outside the process. */
+declare const MATRIX_IMAGE = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAYAAABytg0kAAAAFElEQVR42mNk+M9QzwAFjDAGACPuA/8fMSCgAAAAAElFTkSuQmCC";
+/**
+ * The widest number of a given length: a true minus, thousands separators
+ * and one decimal, every glyph at tabular width. `−1,234,567.0` for 12.
+ */
+declare function widestNumber(length: number, seed?: number): string;
+/** A slot's value at an edge; `undefined` means "leave it out". */
+declare function boundarySlotValue(slot: BlockSlot, name: string, edge: MatrixEdge, seed?: number): unknown;
+/**
+ * One invocation of a definition with every slot at the edge: optional slots
+ * left out at `min` (so defaults are what renders), every slot at `max`.
+ * A slot whose role the profile requires — a source under every figure —
+ * is never optional to that profile, so `requiredRoles` keeps it at `min`.
+ * Columns whose cells must count the rows do; nothing else knows a block.
+ */
+declare function boundaryInvocation(name: string, definition: JsonBlockDefinition, edge: MatrixEdge, seed?: number, requiredRoles?: readonly string[]): Rec;
+/**
+ * The same invocation one past the edge: the first budgeted string a word
+ * over, or the first bounded array an item over. What a slot violation
+ * looks like, so a suite can prove it is reported at the authored pointer.
+ */
+declare function overBudgetInvocation(name: string, definition: JsonBlockDefinition, seed?: number): {
+    invocation: Rec;
+    slot: string;
+    kind: 'words' | 'items';
+} | undefined;
+/** Every definition a template embeds, with the template's own example of it. */
+declare function enumerateBlockDefinitions(template: unknown, templateName: string): BlockMatrixDefinition[];
+/**
+ * A small report with one block at its edge: the chrome at the template's
+ * nominal values (or at the edge, when the chrome block is the one under
+ * test), the block in the first body section, body copy after it.
+ */
+declare function blockCaseDocument(entries: readonly BlockMatrixDefinition[], name: string, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles }?: CaseConditions): Rec;
+/** The whole template with every invocation at the edge. */
+declare function reportCaseDocument(template: unknown, edge: MatrixEdge, theme: string, { font, canvas, requiredRoles }?: CaseConditions): Rec;
+/** Every case the options span, in a stable order. */
+declare function generateBlockMatrix(template: unknown, templateName: string, options: BlockMatrixOptions): BlockMatrixCase[];
 
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
@@ -764,4 +946,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, type InventoryEntry, type InventoryMatch, MacOSCoreTextStager, type MappingStatus, NoopFontStager, type PdfFontInfo, type PdfTextLine, type PdfTextPage, type PdfTextWord, PptxFormatAdapter, type RasterizerCacheStats, type RenderedAnalysis, type RenderedAnalysisInput, type RenderedAnalysisSummary, type RenderedMapping, 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 };
+export { type BlockMatrixCase, type BlockMatrixDefinition, type BlockMatrixOptions, type CaseConditions, type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, FALLBACK_FONTS, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, type InventoryEntry, type InventoryMatch, MATRIX_IMAGE, MacOSCoreTextStager, type MappingStatus, type MatrixCanvas, type MatrixEdge, type MatrixFont, 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, blockCaseDocument, boundaryInvocation, boundarySlotValue, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, enumerateBlockDefinitions, extractPdfFonts, extractPdfTextGeometry, familyRendered, generateBlockMatrix, getFontStager, getRasterizerCacheStats, normalizeForMatch, overBudgetInvocation, parsePdfFonts, parsePdfTextBbox, pdffontsAvailable, pdftotextAvailable, readingOrder, reportCaseDocument, runWithDiagnosticSink, stderrDiagnosticSink, widestNumber };