@json-to-office/jto-ops 4.1.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, QualityDiagnostic } from '@json-to-office/quality';
+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.
  *
@@ -462,6 +476,12 @@ interface InventoryEntry {
     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 +513,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 +538,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 +570,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 +585,37 @@ 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;
 
 /**
  * Make resolved fonts visible to the LibreOffice child process for the
@@ -764,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, 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 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 };

package/dist/index.js

@@ -1947,9 +1947,93 @@ async function extractPdfFonts(pdfPath, options = {}) {
 }
 
 // src/rendered-analysis.ts
+import {
+  QualityEngine
+} from "@json-to-office/quality";
+
+// src/rendered-rules.ts
 import {
   QUALITY_CODES
 } from "@json-to-office/quality";
+function renderedRule(spec) {
+  return {
+    id: spec.id,
+    code: spec.code,
+    description: spec.description,
+    category: spec.category,
+    defaultSeverity: spec.defaultSeverity,
+    defaultCertainty: "rendered",
+    ...spec.formats && { formats: spec.formats },
+    evaluate({ facts }) {
+      const fact = facts.find(isRenderedGeometryFact);
+      if (!fact) return [];
+      return renderedDraftFor(fact).byRule.get(spec.id) ?? [];
+    }
+  };
+}
+var RENDERED_QUALITY_RULES = {
+  id: "rendered",
+  rules: [
+    renderedRule({
+      id: "rendered/clip",
+      code: QUALITY_CODES.RENDERED_CLIP,
+      description: "Words rendered past the page edge by more than 2 pt, or an authored string of which only a leading part rendered (`kind: truncated`, with the share found).",
+      category: "integrity",
+      defaultSeverity: "warning"
+    }),
+    renderedRule({
+      id: "rendered/spill",
+      code: QUALITY_CODES.RENDERED_SPILL,
+      description: "A framed paragraph or slide text box drawn wider (DOCX) or larger (PPTX) than the box it declared.",
+      category: "integrity",
+      defaultSeverity: "warning"
+    }),
+    renderedRule({
+      id: "rendered/overlap",
+      code: QUALITY_CODES.RENDERED_OVERLAP,
+      description: "Two words from different lines whose boxes intersect by more than 30% of the smaller.",
+      category: "integrity",
+      defaultSeverity: "warning"
+    }),
+    renderedRule({
+      id: "rendered/text-missing",
+      code: QUALITY_CODES.RENDERED_TEXT_MISSING,
+      description: "An authored string that appears nowhere in the PDF: fully clipped, hidden, or dropped by the renderer.",
+      category: "integrity",
+      defaultSeverity: "warning"
+    }),
+    renderedRule({
+      id: "rendered/font-substituted",
+      code: QUALITY_CODES.RENDERED_FONT_SUBSTITUTED,
+      description: "A requested family the PDF embeds no face of; a warning when the document declared a source for it, information when the host simply lacks it.",
+      category: "brand",
+      defaultSeverity: "info"
+    }),
+    renderedRule({
+      id: "rendered/empty-page",
+      code: QUALITY_CODES.RENDERED_EMPTY_PAGE,
+      description: "A page with no text at all: a full-page figure is fine, a blank page from a stray break is not.",
+      category: "integrity",
+      defaultSeverity: "info"
+    }),
+    renderedRule({
+      id: "rendered/heading-stranded",
+      code: QUALITY_CODES.RENDERED_HEADING_STRANDED,
+      description: "A heading that is the last body line on its page.",
+      category: "composition",
+      defaultSeverity: "warning",
+      formats: ["docx"]
+    }),
+    renderedRule({
+      id: "rendered/paragraph-split",
+      code: QUALITY_CODES.RENDERED_PARAGRAPH_SPLIT,
+      description: "A paragraph leaving one line alone on either side of a page break (`kind: orphan` or `widow`).",
+      category: "composition",
+      defaultSeverity: "info",
+      formats: ["docx"]
+    })
+  ]
+};
 
 // src/rendered-text-match.ts
 function normalizeForMatch(value) {
@@ -2142,7 +2226,7 @@ function assignInventory(pages, inventory) {
     });
   });
   const body = indexDocument(pages, chromeWords);
-  const claimed = /* @__PURE__ */ new Set();
+  const claimed = /* @__PURE__ */ new Map();
   let cursor = 0;
   for (const entry of inventory) {
     if (entry.repeats) continue;
@@ -2154,7 +2238,7 @@ function assignInventory(pages, inventory) {
     }
     let all = findOccurrences(body, segments);
     let partial;
-    if (all.length === 0 && segments.length === 1) {
+    if (all.length === 0 && segments.length === 1 && !entry.optional) {
       const prefix = longestRenderedPrefix(body, needle);
       if (prefix) {
         all = [occurrence(body, prefix.at, prefix.at + prefix.length)];
@@ -2162,10 +2246,29 @@ function assignInventory(pages, inventory) {
       }
     }
     if (all.length === 0) {
-      results.set(entry, { entry, needle, status: "missing", occurrences: [] });
+      results.set(entry, {
+        entry,
+        needle,
+        status: entry.optional ? "skipped" : "missing",
+        occurrences: []
+      });
       continue;
     }
-    const free = all.filter((o) => !claimed.has(o.at));
+    let free = all.filter((o) => !claimed.has(o.at));
+    if (free.length === 0 && !entry.optional) {
+      const held = all.find((o) => claimed.get(o.at)?.optional);
+      if (held) {
+        const holder = claimed.get(held.at);
+        claimed.delete(held.at);
+        results.set(holder, {
+          entry: holder,
+          needle: results.get(holder)?.needle ?? "",
+          status: "skipped",
+          occurrences: []
+        });
+        free = [held];
+      }
+    }
     if (free.length === 0) {
       results.set(entry, {
         entry,
@@ -2176,7 +2279,7 @@ function assignInventory(pages, inventory) {
       continue;
     }
     const chosen = free.find((o) => o.at >= cursor) ?? free[0];
-    claimed.add(chosen.at);
+    claimed.set(chosen.at, entry);
     cursor = chosen.at;
     results.set(entry, {
       entry,
@@ -2193,15 +2296,23 @@ function assignInventory(pages, inventory) {
 }
 
 // src/rendered-analysis.ts
+function isRenderedGeometryFact(fact) {
+  return fact.kind === "rendered/geometry";
+}
+var drafts = /* @__PURE__ */ new WeakMap();
+function renderedDraftFor(fact) {
+  let draft = drafts.get(fact);
+  if (!draft) {
+    draft = draftRenderedFindings(fact.input);
+    drafts.set(fact, draft);
+  }
+  return draft;
+}
 var VISIBLE_SPILL_PT = 2;
 var OVERLAP_FRACTION = 0.3;
 function finding(draft) {
-  const { ruleId, mapping, page, context, ...rest } = draft;
+  const { mapping, page, context, ...rest } = draft;
   return {
-    source: "quality",
-    ruleId,
-    certainty: "rendered",
-    blocking: false,
     ...rest,
     context: {
       ...context,
@@ -2259,7 +2370,7 @@ function unionBox(parts) {
     { xMin: Infinity, yMin: Infinity, xMax: -Infinity, yMax: -Infinity }
   );
 }
-function analyzeRenderedDocument(input) {
+function draftRenderedFindings(input) {
   const { pages, format } = input;
   const { matches, chromeWords } = assignInventory(pages, input.inventory);
   const owners = wordOwners(matches);
@@ -2293,9 +2404,6 @@ function analyzeRenderedDocument(input) {
     findings.push(
       finding({
         ruleId: "rendered/clip",
-        code: QUALITY_CODES.RENDERED_CLIP,
-        category: "integrity",
-        severity: "warning",
         mapping: bucket.match ? "mapped" : "unmapped",
         page: bucket.page,
         path: bucket.match?.entry.path ?? "",
@@ -2320,9 +2428,6 @@ function analyzeRenderedDocument(input) {
     findings.push(
       finding({
         ruleId: "rendered/clip",
-        code: QUALITY_CODES.RENDERED_CLIP,
-        category: "integrity",
-        severity: "warning",
         mapping: "mapped",
         page: o.endPageIndex + 1,
         path: match.entry.path,
@@ -2359,9 +2464,6 @@ function analyzeRenderedDocument(input) {
       findings.push(
         finding({
           ruleId: "rendered/spill",
-          code: QUALITY_CODES.RENDERED_SPILL,
-          category: "integrity",
-          severity: "warning",
           mapping: "mapped",
           page: o.pageIndex + 1,
           path: match.entry.path,
@@ -2407,9 +2509,6 @@ function analyzeRenderedDocument(input) {
         findings.push(
           finding({
             ruleId: "rendered/overlap",
-            code: QUALITY_CODES.RENDERED_OVERLAP,
-            category: "integrity",
-            severity: "warning",
             mapping,
             page: pageIndex + 1,
             path: pathA || pathB,
@@ -2432,9 +2531,6 @@ function analyzeRenderedDocument(input) {
     findings.push(
       finding({
         ruleId: "rendered/text-missing",
-        code: QUALITY_CODES.RENDERED_TEXT_MISSING,
-        category: "integrity",
-        severity: "warning",
         mapping: "mapped",
         path: match.entry.path,
         message: `"${excerpt(match.entry.text)}" does not appear anywhere in the rendered pages.`,
@@ -2456,8 +2552,6 @@ function analyzeRenderedDocument(input) {
       findings.push(
         finding({
           ruleId: "rendered/font-substituted",
-          code: QUALITY_CODES.RENDERED_FONT_SUBSTITUTED,
-          category: "brand",
           severity: requested.declared ? "warning" : "info",
           mapping: requested.path ? "mapped" : "unmapped",
           path: requested.path ?? "",
@@ -2478,9 +2572,6 @@ function analyzeRenderedDocument(input) {
     findings.push(
       finding({
         ruleId: "rendered/empty-page",
-        code: QUALITY_CODES.RENDERED_EMPTY_PAGE,
-        category: "integrity",
-        severity: "info",
         mapping: "unmapped",
         page: pageIndex + 1,
         path: "",
@@ -2503,9 +2594,6 @@ function analyzeRenderedDocument(input) {
       findings.push(
         finding({
           ruleId: "rendered/heading-stranded",
-          code: QUALITY_CODES.RENDERED_HEADING_STRANDED,
-          category: "composition",
-          severity: "warning",
           mapping: "mapped",
           page: part.pageIndex + 1,
           path: match.entry.path,
@@ -2539,9 +2627,6 @@ function analyzeRenderedDocument(input) {
       findings.push(
         finding({
           ruleId: "rendered/paragraph-split",
-          code: QUALITY_CODES.RENDERED_PARAGRAPH_SPLIT,
-          category: "composition",
-          severity: "info",
           mapping: "mapped",
           page: (which === "orphan" ? first.pageIndex : last.pageIndex) + 1,
           path: match.entry.path,
@@ -2563,27 +2648,80 @@ function analyzeRenderedDocument(input) {
     skipped: 0
   };
   for (const match of matches) inventory[match.status] += 1;
+  const byRule = /* @__PURE__ */ new Map();
+  for (const draft of findings) {
+    const bucket = byRule.get(draft.ruleId);
+    if (bucket) bucket.push(draft);
+    else byRule.set(draft.ruleId, [draft]);
+  }
+  return {
+    drafts: findings,
+    byRule,
+    inventory,
+    // The same gate the check itself runs under: an empty font list
+    // verified nothing, and must not read as "nothing was substituted".
+    ...input.fonts && input.fonts.length > 0 && input.requestedFonts && {
+      fonts: { requested: input.requestedFonts.length, substituted }
+    }
+  };
+}
+var engine;
+function renderedEngine() {
+  engine ??= new QualityEngine(RENDERED_QUALITY_RULES.rules);
+  return engine;
+}
+function analyzeRenderedDocument(input, options = {}) {
+  const fact = {
+    id: "rendered:geometry",
+    kind: "rendered/geometry",
+    path: "",
+    input
+  };
+  const analysis = renderedEngine().analyzeSync(
+    {
+      format: input.format,
+      model: void 0,
+      facts: [fact],
+      provenance: {},
+      ...input.renderer !== void 0 && { renderer: input.renderer }
+    },
+    options
+  );
+  let draft;
+  try {
+    draft = renderedDraftFor(fact);
+  } catch {
+    draft = void 0;
+  }
   const byMapping = {
     mapped: 0,
     ambiguous: 0,
     unmapped: 0
   };
-  for (const f of findings) {
+  for (const f of analysis.diagnostics) {
     byMapping[f.context?.mapping ?? "unmapped"] += 1;
   }
   return {
-    findings,
+    findings: analysis.diagnostics,
     summary: {
-      pages: pages.length,
-      words: pages.reduce((n, p) => n + p.words.length, 0),
-      inventory,
+      pages: input.pages.length,
+      words: input.pages.reduce((n, p) => n + p.words.length, 0),
+      inventory: draft?.inventory ?? {
+        mapped: 0,
+        ambiguous: 0,
+        missing: 0,
+        skipped: 0
+      },
       findings: byMapping,
-      // The same gate the check itself runs under: an empty font list
-      // verified nothing, and must not read as "nothing was substituted".
-      ...input.fonts && input.fonts.length > 0 && input.requestedFonts && {
-        fonts: { requested: input.requestedFonts.length, substituted }
+      ...draft?.fonts && { fonts: draft.fonts },
+      suppressed: analysis.suppressedCount,
+      blocked: analysis.blocked,
+      truncated: analysis.truncated,
+      ...analysis.profileId !== void 0 && {
+        profileId: analysis.profileId
       }
-    }
+    },
+    analysis
   };
 }
 export {
@@ -2592,6 +2730,7 @@ export {
   MacOSCoreTextStager,
   NoopFontStager,
   PptxFormatAdapter,
+  RENDERED_QUALITY_RULES,
   VISIBLE_SPILL_PT,
   WindowsFontStager,
   analyzeRenderedDocument,