@intentic/fileq 1.317.0 → 1.318.0

package/src/lib/check/text-fit.ts

@@ -0,0 +1,105 @@
+// Estimates how much room a run of text needs, from character classes rather than the font's own metrics. Good enough
+// to say "about nine lines of 24 pt will not fit in a box 1.2 in tall", never good enough to say it for certain: the
+// real answer depends on the font the viewer substitutes, which is why every finding built on this is a warning and
+// points at `fileq render` for the look that settles it.
+
+export interface Paragraph {
+    readonly text: string;
+    readonly sizePt: number;
+    readonly bold: boolean;
+    /** Multiple of single spacing (1 for single); ignored when `lineHeightPt` gives the height in points. */
+    readonly lineSpacing: number;
+    /** Exact line height in points when the paragraph sets one. */
+    readonly lineHeightPt?: number | undefined;
+    readonly spaceBeforePt: number;
+    readonly spaceAfterPt: number;
+}
+
+// Average advance of a character as a fraction of the font size, by class. Calibrated against Arial/Liberation Sans,
+// where running English text averages about half an em per character.
+const widthEm = (char: string): number => {
+    if (/\s/.test(char)) {
+        return 0.28;
+    }
+    if (/[\u1100-\u11ff\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/.test(char)) {
+        return 1;
+    }
+    if (/[iljtfrI.,:;'!|()[\]]/.test(char)) {
+        return 0.3;
+    }
+    if (/[mwMW@%]/.test(char)) {
+        return 0.85;
+    }
+    if (/[A-Z]/.test(char)) {
+        return 0.66;
+    }
+    if (/\d/.test(char)) {
+        return 0.556;
+    }
+    if (/[a-z]/.test(char)) {
+        return 0.52;
+    }
+    return 0.6;
+};
+
+const BOLD_WIDENING = 1.07;
+// Single spacing in PowerPoint and LibreOffice is about 1.2 times the font size.
+const SINGLE_LINE = 1.2;
+
+const textWidthPt = (text: string, sizePt: number, bold: boolean): number =>
+    [...text].reduce((sum, char) => sum + widthEm(char), 0) * sizePt * (bold ? BOLD_WIDENING : 1);
+
+/** Lines one paragraph wraps to at `widthPt`, greedy by word, a word wider than the line broken where it runs out. */
+export const wrappedLines = (paragraph: Paragraph, widthPt: number): number => {
+    let lines = 0;
+    for (const hardLine of paragraph.text.split("\n")) {
+        let used = 0;
+        let count = 1;
+        for (const word of hardLine.split(/(?<=\s)/)) {
+            const width = textWidthPt(word, paragraph.sizePt, paragraph.bold);
+            const visible = textWidthPt(word.trimEnd(), paragraph.sizePt, paragraph.bold);
+            if (used > 0 && used + visible > widthPt) {
+                count += 1;
+                used = 0;
+            }
+            if (used === 0 && visible > widthPt && widthPt > 0) {
+                count += Math.ceil(visible / widthPt) - 1;
+                used = visible % widthPt;
+                continue;
+            }
+            used += width;
+        }
+        lines += count;
+    }
+    return lines;
+};
+
+const lineHeightOf = (paragraph: Paragraph): number => paragraph.lineHeightPt ?? paragraph.sizePt * SINGLE_LINE * paragraph.lineSpacing;
+
+export interface TextEstimate {
+    readonly heightPt: number;
+    readonly lines: number;
+    /** The widest unwrapped line, for a box that does not wrap. */
+    readonly widestPt: number;
+    /** The size most of the text is set in, for the message. */
+    readonly sizePt: number;
+}
+
+/** Height of the paragraphs set in a column `widthPt` wide; `wrap: false` keeps every hard line on one line. */
+export const estimateText = (paragraphs: readonly Paragraph[], widthPt: number, wrap: boolean): TextEstimate => {
+    let heightPt = 0;
+    let lines = 0;
+    let widestPt = 0;
+    const weight = new Map<number, number>();
+    paragraphs.forEach((paragraph, index) => {
+        const count = wrap ? wrappedLines(paragraph, widthPt) : paragraph.text.split("\n").length;
+        lines += count;
+        heightPt += count * lineHeightOf(paragraph) + (index === 0 ? 0 : paragraph.spaceBeforePt) + (index === paragraphs.length - 1 ? 0 : paragraph.spaceAfterPt);
+        for (const hardLine of paragraph.text.split("\n")) {
+            widestPt = Math.max(widestPt, textWidthPt(hardLine, paragraph.sizePt, paragraph.bold));
+        }
+        weight.set(paragraph.sizePt, (weight.get(paragraph.sizePt) ?? 0) + Math.max(1, paragraph.text.length));
+    });
+    const sizePt = [...weight.entries()].toSorted((a, b) => b[1] - a[1])[0]?.[0] ?? 18;
+    return { heightPt, lines, widestPt, sizePt };
+};

package/src/lib/check/xlsx.ts

@@ -0,0 +1,163 @@
+// Structural checks over an Excel workbook: cells whose saved value is an error (#REF!, #DIV/0!, #NAME?, …),
+// formulas that point at a deleted range, formulas saved without a value, names that lead nowhere, and links to other
+// workbooks. Worksheets are scanned as text, not built into a tree: a sheet can be tens of megabytes of cells.
+//
+// The error-value and missing-cached-value rules are adapted from SurfSense's XLSX artifact verification
+// (surfsense_backend/app/artifacts/verification/formats/xlsx.py, Copyright (c) SurfSense, Apache-2.0,
+// https://github.com/MODSetter/SurfSense; see this package's NOTICE). Changed here: each finding names its cell, and a
+// formula with no saved value is a warning, since every spreadsheet application computes it on open.
+import { decodeEntities } from "../xml.js";
+import { error, excerpt, plural, warning, type CheckReport, type Finding } from "./finding.js";
+import { mainPartOf, missingTargetFindings, NotAPackage, openPackage, packageFindings, type OoxmlPackage } from "./package.js";
+import { childAt, childNamed, childrenNamed, isElement, type XmlElement } from "./xml-tree.js";
+
+const DEFAULT_MAIN = "xl/workbook.xml";
+// Past this many cells of one kind on one sheet, the rest are counted, not listed.
+const LISTED_PER_SHEET = 10;
+
+const CELL = /<((?:\w+:)?)c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1c>)/g;
+const FORMULA = /<((?:\w+:)?)f\b[^>]*?(?:\/>|>([\s\S]*?)<\/\1f>)/;
+const VALUE = /<((?:\w+:)?)v>([\s\S]*?)<\/\1v>/;
+const INLINE = /<((?:\w+:)?)is\b/;
+
+const attributeIn = (attributes: string, name: string): string | undefined => new RegExp(`(?:^|\\s)${name}="([^"]*)"`).exec(attributes)?.[1];
+
+// A sheet name as a formula would quote it: `Sheet1!B4`, `'Q3 plan'!B4`.
+const cellRef = (sheet: string, ref: string): string => (/^[A-Za-z_][\w.]*$/.test(sheet) ? `${sheet}!${ref}` : `'${sheet.replaceAll("'", "''")}'!${ref}`);
+
+interface SheetScan {
+    readonly errors: Finding[];
+    readonly uncached: string[];
+    readonly filled: number;
+}
+
+const scanSheet = (sheet: string, xml: string): SheetScan => {
+    const errors: Finding[] = [];
+    const uncached: string[] = [];
+    let listed = 0;
+    let unlisted = 0;
+    let filled = 0;
+    const report = (finding: Finding): void => {
+        if (listed < LISTED_PER_SHEET) {
+            errors.push(finding);
+            listed += 1;
+        } else {
+            unlisted += 1;
+        }
+    };
+    for (const match of xml.matchAll(CELL)) {
+        const attributes = match[2] ?? "";
+        const inner = match[3] ?? "";
+        const ref = cellRef(sheet, attributeIn(attributes, "r") ?? "?");
+        const formula = FORMULA.exec(inner);
+        const value = VALUE.exec(inner);
+        const formulaText = formula === null ? undefined : decodeEntities(formula[2] ?? "");
+        if (formula !== null || value !== null || INLINE.test(inner)) {
+            filled += 1;
+        }
+        const shown = formulaText === undefined || formulaText === "" ? "" : ` from =${formulaText}`;
+        if (attributeIn(attributes, "t") === "e") {
+            report(error("formula-error", ref, `shows ${decodeEntities(value?.[2] ?? "an error")}${shown}: fix the formula or its inputs`));
+        } else if (formulaText?.includes("#REF!") === true) {
+            report(error("formula-error", ref, `the formula =${formulaText} points at a deleted range (#REF!)`));
+        } else if (formula !== null && value === null) {
+            uncached.push(ref);
+        }
+    }
+    if (unlisted > 0) {
+        errors.push(error("formula-error", sheet, `and ${plural(unlisted, "more cell")} with errors on this sheet`));
+    }
+    return { errors, uncached, filled };
+};
+
+const uncachedFinding = (sheet: string, cells: readonly string[], recalculates: boolean): Finding => {
+    const shown = cells.slice(0, 5).map((cell) => cell.slice(cell.lastIndexOf("!") + 1)).join(", ");
+    const more = cells.length > 5 ? ", …" : "";
+    const onOpen = recalculates ? "the workbook asks to be recalculated on open, so spreadsheet applications fill them in" : "Excel, LibreOffice and Google Sheets compute them on open";
+    return warning(
+        "formula-uncached",
+        sheet,
+        `${plural(cells.length, "formula")} saved with no value (${shown}${more}): ${onOpen}, but previews and anything that reads the file (pandas, fileq read) see blanks; write the value with the formula, or recalculate in LibreOffice`,
+    );
+};
+
+const openWorkbook = (bytes: Uint8Array): OoxmlPackage | CheckReport => {
+    try {
+        return openPackage(bytes);
+    } catch (cause) {
+        if (cause instanceof NotAPackage) {
+            return { format: "xlsx", findings: [error("unreadable", "", `${cause.message}: this is not an Excel file (or it is password-protected)`)], notes: [] };
+        }
+        throw cause;
+    }
+};
+
+const namesFindings = (workbook: XmlElement | undefined): Finding[] => {
+    const names = workbook === undefined ? undefined : childNamed(workbook, "x:definedNames");
+    return (names === undefined ? [] : childrenNamed(names, "x:definedName")).flatMap((name) => {
+        const target = name.children.filter((child): child is string => !isElement(child)).join("");
+        return target.includes("#REF!") ? [error("broken-name", "", `the defined name "${name.attrs["name"] ?? "?"}" refers to ${excerpt(target)}, a deleted range`)] : [];
+    });
+};
+
+const externalFindings = (pkg: OoxmlPackage): Finding[] => {
+    const links = [...pkg.names].filter((name) => /^xl\/externalLinks\/externalLink\d+\.xml$/.test(name));
+    return links.map((link) => {
+        const target = [...pkg.rels(link).values()].find((relationship) => relationship.external)?.target ?? "another file";
+        return warning("external-link", "", `the workbook takes values from ${target}; they go stale, or break, once the file is sent without it`);
+    });
+};
+
+interface SheetsResult {
+    readonly findings: Finding[];
+    readonly filled: number;
+}
+
+const sheetsFindings = (pkg: OoxmlPackage, main: string, sheets: readonly XmlElement[], recalculates: boolean): SheetsResult => {
+    const rels = pkg.rels(main);
+    const findings: Finding[] = [];
+    let filled = 0;
+    for (const sheet of sheets) {
+        const name = sheet.attrs["name"] ?? "?";
+        const relationship = rels.get(sheet.attrs["r:id"] ?? "");
+        if (relationship === undefined || relationship.external || !pkg.has(relationship.target)) {
+            findings.push(error("missing-part", name, "the sheet list names a sheet that is not in the file; Excel will offer to repair the workbook"));
+            continue;
+        }
+        // A chart sheet has no cells, and a sheet over the size cap is named in the notes.
+        const xml = relationship.kind === "worksheet" ? pkg.text(relationship.target) : undefined;
+        const scan = xml === undefined ? undefined : scanSheet(name, xml);
+        if (scan === undefined) {
+            continue;
+        }
+        filled += scan.filled;
+        findings.push(...scan.errors, ...(scan.uncached.length > 0 ? [uncachedFinding(name, scan.uncached, recalculates)] : []));
+        findings.push(...missingTargetFindings(pkg, relationship.target, name));
+    }
+    return { findings, filled };
+};
+
+export const checkXlsx = (bytes: Uint8Array): CheckReport => {
+    const pkg = openWorkbook(bytes);
+    if ("findings" in pkg) {
+        return pkg;
+    }
+    const main = mainPartOf(pkg, DEFAULT_MAIN);
+    const findings = packageFindings(pkg, main);
+    const notes = pkg.skipped.map((part) => `not checked: ${part} is too large to read`);
+    const workbook = pkg.xml(main);
+    const sheetList = childAt(workbook, "x:sheets");
+    const sheets = sheetList === undefined ? [] : childrenNamed(sheetList, "x:sheet");
+    if (workbook !== undefined && sheets.length === 0) {
+        findings.push(error("no-sheets", "", "the workbook has no sheets"));
+    }
+    const fullCalcOnLoad = childAt(workbook, "x:calcPr")?.attrs["fullCalcOnLoad"];
+    const scanned = sheetsFindings(pkg, main, sheets, fullCalcOnLoad === "1" || fullCalcOnLoad === "true");
+    findings.push(...scanned.findings);
+    if (sheets.length > 0 && scanned.filled === 0 && pkg.skipped.length === 0) {
+        findings.push(warning("no-data", "", "every sheet is empty"));
+    }
+    const listed = new Set(sheets.flatMap((sheet) => sheet.attrs["r:id"] ?? []));
+    findings.push(...namesFindings(workbook), ...externalFindings(pkg), ...missingTargetFindings(pkg, main, "", listed));
+    return { format: "xlsx", extent: plural(sheets.length, "sheet"), findings, notes };
+};

package/src/lib/check/xml-tree.ts

@@ -0,0 +1,186 @@
+import { decodeEntities } from "../xml.js";
+
+// A small non-validating XML reader for the checks. The derivers get by with a regex over a part's text; a check needs
+// the tree (a shape's OWN geometry rather than a grouped child's, a paragraph's own runs, a field's begin and end).
+// Names come out under the specification's prefixes whatever the file declared: a part rewritten by a script that
+// renamed `p:` to `ns0:` is still the same presentation, and a check that matched on the written prefix would pass it.
+// No DTD, no entity expansion beyond the five predefined and numeric references: a part is data, never instructions.
+
+export interface XmlElement {
+    /** Qualified name under the canonical prefix of its namespace (`p:sp`, `w:t`); the written one for an unknown namespace. */
+    readonly name: string;
+    /** Attributes by qualified name, canonical prefixes as above; unprefixed attributes keep their bare name. */
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly children: (XmlElement | string)[];
+}
+
+// Transitional and Strict OOXML name the same vocabulary under two URIs; both read as one prefix.
+const CANONICAL = new Map<string, string>([
+    ["http://schemas.openxmlformats.org/presentationml/2006/main", "p"],
+    ["http://purl.oclc.org/ooxml/presentationml/main", "p"],
+    ["http://schemas.openxmlformats.org/drawingml/2006/main", "a"],
+    ["http://purl.oclc.org/ooxml/drawingml/main", "a"],
+    ["http://schemas.openxmlformats.org/officeDocument/2006/relationships", "r"],
+    ["http://purl.oclc.org/ooxml/officeDocument/relationships", "r"],
+    ["http://schemas.openxmlformats.org/wordprocessingml/2006/main", "w"],
+    ["http://purl.oclc.org/ooxml/wordprocessingml/main", "w"],
+    ["http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing", "wp"],
+    ["http://purl.oclc.org/ooxml/drawingml/wordprocessingDrawing", "wp"],
+    ["http://schemas.openxmlformats.org/spreadsheetml/2006/main", "x"],
+    ["http://purl.oclc.org/ooxml/spreadsheetml/main", "x"],
+    ["http://schemas.openxmlformats.org/package/2006/relationships", "rel"],
+    ["http://schemas.openxmlformats.org/markup-compatibility/2006", "mc"],
+]);
+
+const TOKEN =
+    /<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<\?[\s\S]*?\?>|<!DOCTYPE[^>[]*(?:\[[\s\S]*?\])?\s*>|<\/([^\s>]+)\s*>|<([^\s/>!?]+)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>/g;
+const ATTRIBUTE = /([^\s=]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+type Scope = ReadonlyMap<string, string>;
+
+const canonicalName = (written: string, scope: Scope, isAttribute: boolean): string => {
+    const colon = written.indexOf(":");
+    const prefix = colon === -1 ? "" : written.slice(0, colon);
+    const local = colon === -1 ? written : written.slice(colon + 1);
+    // An unprefixed attribute belongs to no namespace; an unprefixed element to the default one.
+    if (colon === -1 && isAttribute) {
+        return written;
+    }
+    const uri = scope.get(prefix);
+    const canonical = uri === undefined ? undefined : CANONICAL.get(uri);
+    if (canonical !== undefined) {
+        return `${canonical}:${local}`;
+    }
+    return written;
+};
+
+interface Frame {
+    readonly element: XmlElement;
+    /** The name as the file wrote it, which is what its closing tag repeats. */
+    readonly written: string;
+    readonly scope: Scope;
+}
+
+const isDeclaration = (name: string): boolean => name === "xmlns" || name.startsWith("xmlns:");
+
+// An opening tag as an element under `parent`: its namespace declarations extend the parent's scope, and its names are
+// canonicalised under the scope that results.
+const openElement = (parent: Frame, written: string, attributeText: string): Frame => {
+    const pairs: [string, string][] = [...attributeText.matchAll(ATTRIBUTE)].map((attribute) => [attribute[1] ?? "", decodeEntities(attribute[2] ?? attribute[3] ?? "")]);
+    const declarations = pairs.filter(([name]) => isDeclaration(name));
+    const scope =
+        declarations.length === 0
+            ? parent.scope
+            : new Map([...parent.scope, ...declarations.map(([name, uri]): [string, string] => [name === "xmlns" ? "" : name.slice(6), uri])]);
+    const attrs = Object.fromEntries(pairs.filter(([name]) => !isDeclaration(name)).map(([name, value]) => [canonicalName(name, scope, true), value]));
+    const element: XmlElement = { name: canonicalName(written, scope, false), attrs, children: [] };
+    parent.element.children.push(element);
+    return { element, written, scope };
+};
+
+// Whitespace between elements is layout; inside a text-bearing element (`a:t`, `w:t`) it is content.
+const appendText = (frame: Frame | undefined, raw: string, decode: boolean): void => {
+    if (frame === undefined || raw === "") {
+        return;
+    }
+    const textBearing = frame.element.name.endsWith(":t") || frame.element.name === "t";
+    if (raw.trim() === "" && !textBearing) {
+        return;
+    }
+    frame.element.children.push(decode ? decodeEntities(raw) : raw);
+};
+
+/** The root element of `text`; an empty synthetic root when the text holds no element at all. */
+export const parseXml = (text: string): XmlElement => {
+    const root: XmlElement = { name: "#document", attrs: {}, children: [] };
+    const stack: Frame[] = [{ element: root, written: "#document", scope: new Map() }];
+    let last = 0;
+    for (const match of text.matchAll(TOKEN)) {
+        appendText(stack.at(-1), text.slice(last, match.index), true);
+        last = match.index + match[0].length;
+        const [, cdata, closing, opening, attributeText, selfClosing] = match;
+        if (cdata !== undefined) {
+            appendText(stack.at(-1), cdata, false);
+        } else if (closing !== undefined) {
+            // Pops to the matching open tag; a stray close tag (a malformed part) is ignored rather than fatal.
+            const at = stack.findLastIndex((frame) => frame.written === closing);
+            stack.length = at > 0 ? at : stack.length;
+        } else if (opening !== undefined) {
+            const frame = openElement(stack.at(-1) ?? { element: root, written: "#document", scope: new Map() }, opening, attributeText ?? "");
+            if (selfClosing !== "/") {
+                stack.push(frame);
+            }
+        }
+        // Anything else is a comment, a processing instruction or a doctype, none of which is content.
+    }
+    return root.children.find((child): child is XmlElement => typeof child !== "string") ?? root;
+};
+
+export const isElement = (node: XmlElement | string): node is XmlElement => typeof node !== "string";
+
+/** Direct children named `name`. */
+export const childrenNamed = (element: XmlElement, name: string): XmlElement[] =>
+    element.children.filter((child): child is XmlElement => isElement(child) && child.name === name);
+
+/** The first direct child named `name`. */
+export const childNamed = (element: XmlElement, name: string): XmlElement | undefined =>
+    element.children.find((child): child is XmlElement => isElement(child) && child.name === name);
+
+/** The element at the end of a path of direct children (`childAt(sp, "p:nvSpPr", "p:nvPr", "p:ph")`). */
+export const childAt = (element: XmlElement | undefined, ...path: readonly string[]): XmlElement | undefined => {
+    let current = element;
+    for (const name of path) {
+        if (current === undefined) {
+            return undefined;
+        }
+        current = childNamed(current, name);
+    }
+    return current;
+};
+
+/** Every descendant named `name`, in document order (the element itself excluded). */
+export const descendantsNamed = (element: XmlElement, name: string): XmlElement[] => {
+    const found: XmlElement[] = [];
+    const visit = (node: XmlElement): void => {
+        for (const child of node.children) {
+            if (isElement(child)) {
+                if (child.name === name) {
+                    found.push(child);
+                }
+                visit(child);
+            }
+        }
+    };
+    visit(element);
+    return found;
+};
+
+/** Every element in the subtree, the root included, in document order. */
+export const everyElement = (element: XmlElement): XmlElement[] => {
+    const found: XmlElement[] = [element];
+    const visit = (node: XmlElement): void => {
+        for (const child of node.children) {
+            if (isElement(child)) {
+                found.push(child);
+                visit(child);
+            }
+        }
+    };
+    visit(element);
+    return found;
+};
+
+/** The text of every descendant element named `textName` (`a:t`, `w:t`), joined. */
+export const textIn = (element: XmlElement, textName: string): string =>
+    descendantsNamed(element, textName)
+        .map((node) => node.children.filter((child): child is string => typeof child === "string").join(""))
+        .join("");
+
+/** An integer attribute; undefined when absent or not a whole number. */
+export const intAttr = (element: XmlElement | undefined, name: string): number | undefined => {
+    const raw = element?.attrs[name];
+    if (raw === undefined || !/^-?\d+$/.test(raw.trim())) {
+        return undefined;
+    }
+    return Number(raw);
+};

package/src/lib/derivers/image.ts

@@ -5,7 +5,8 @@ import type { DerivedDoc, Deriver } from "./deriver.js";
 
 // exifr is CommonJS behind a `main` field with no exports map, so a named `import { parse }` type-checks but throws at
 // load; the default import is its module.exports under Node and under a bundler alike (the Claude Code plugin bundles
-// fileq, and a `createRequire` call is the one form a bundle cannot follow).
+// fileq, and so does the desktop app's compiled file server, and a `createRequire` call is the one form a bundle cannot
+// follow: there it failed every derive with "Cannot find module 'exifr'").
 // oxlint-disable-next-line import/no-named-as-default-member -- the named import this rule asks for is the one that throws at load.
 const { parse: parseExif } = exifr;
 

package/src/lib/formats.ts

@@ -126,6 +126,12 @@ export const detectFormat = async (absPath: string): Promise<Format | undefined>
     return byExtension;
 };
 
+/**
+ * detectFormat, then the extension when magic names something fileq does not read: a password-protected docx is an
+ * encrypted container, not a zip, and a command that checks or draws documents still owes it its format's answer.
+ */
+export const claimedFormat = async (absPath: string): Promise<Format | undefined> => (await detectFormat(absPath)) ?? EXTENSION_FORMAT[extname(absPath).toLowerCase()];
+
 // Formats whose text diff is already the better reading: a textconv over them would replace a line diff with a
 // rendering of the same text.
 const TEXT_UNDERNEATH: ReadonlySet<Format> = new Set(["html"]);

package/src/lib/render/convert.ts

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { promisify } from "node:util";
+import { errorMessage, isMissing } from "@intentic/base/errors";
+import { onPath } from "../tools.js";
+import { runsOf } from "./pages.js";
+
+// The two external steps of `fileq render`: an office document to PDF through LibreOffice, and PDF pages to PNG
+// through poppler's pdftoppm or MuPDF's mutool. fileq carries no renderer of its own: a faithful one is LibreOffice-sized,
+// and a missing tool is named with what installs it rather than papered over with a worse picture.
+
+const run = promisify(execFile);
+
+// A first conversion also builds LibreOffice's profile, which is most of its time; a long deck takes longer still.
+const CONVERT_TIMEOUT_MS = 180_000;
+const RASTER_TIMEOUT_MS = 120_000;
+
+export class ToolMissing extends Error {}
+export class ConvertFailed extends Error {}
+
+export type Rasterizer = "pdftoppm" | "mutool";
+
+/** A folder's entries; none when it does not exist (yet, or because a tool never wrote it). */
+export const listDir = async (dir: string): Promise<string[]> => {
+    try {
+        return await readdir(dir);
+    } catch (cause) {
+        if (isMissing(cause)) {
+            return [];
+        }
+        throw cause;
+    }
+};
+
+// In an Intentic sandbox (its `environment` command is on PATH) the tools are the opt-in `office` image pack, which an
+// agent asks the owner for by name; anywhere else they are ordinary packages.
+const OFFICE_PACK = 'ask the owner for the office image pack (LibreOffice and poppler) with `environment propose office --pack --why "to look at the document I made"`: it arrives with the next rebuild; until then say the document was checked but not seen';
+
+const inSandbox = (): boolean => onPath("environment");
+
+/** The rasterizer on PATH, poppler's first; throws ToolMissing with what to install when there is none. */
+export const rasterizer = (): Rasterizer => {
+    if (onPath("pdftoppm")) {
+        return "pdftoppm";
+    }
+    if (onPath("mutool")) {
+        return "mutool";
+    }
+    const remedy = inSandbox() ? OFFICE_PACK : "install one (Debian/Ubuntu: apt-get install poppler-utils)";
+    throw new ToolMissing(`rendering pages needs pdftoppm (poppler-utils) or mutool (mupdf-tools) on PATH, and neither is here: ${remedy}`);
+};
+
+/** LibreOffice's binary on PATH; throws ToolMissing with what to install when there is none. */
+export const office = (format: string): string => {
+    for (const name of ["soffice", "libreoffice"]) {
+        if (onPath(name)) {
+            return name;
+        }
+    }
+    const remedy = inSandbox()
+        ? OFFICE_PACK
+        : "install it (Debian/Ubuntu: apt-get install libreoffice-impress-nogui libreoffice-writer-nogui libreoffice-calc-nogui), or export the file to PDF yourself and render that";
+    throw new ToolMissing(`rendering a ${format} needs LibreOffice (soffice) on PATH to lay it out, and it is not here: ${remedy}`);
+};
+
+// Impress leaves hidden slides out of a PDF by default, which would shift every later page off its slide number.
+const IMPRESS_PDF = 'pdf:impress_pdf_Export:{"ExportHiddenSlides":{"type":"boolean","value":"true"}}';
+const pdfFilter = (format: string): string => (format === "pptx" || format === "odp" ? IMPRESS_PDF : "pdf");
+
+/**
+ * Converts an office document to PDF in `workDir` and answers the PDF's path. Each run gets its own LibreOffice
+ * profile, so two conversions at once never meet over a lock file, and none of them touches the user's own profile.
+ */
+export const toPdf = async (binary: string, absPath: string, format: string, workDir: string): Promise<string> => {
+    const outDir = join(workDir, "pdf");
+    const args = [
+        "--headless",
+        "--norestore",
+        "--nologo",
+        "--nolockcheck",
+        `-env:UserInstallation=file://${join(workDir, "profile")}`,
+        "--convert-to",
+        pdfFilter(format),
+        "--outdir",
+        outDir,
+        absPath,
+    ];
+    let output = "";
+    try {
+        const result = await run(binary, args, { timeout: CONVERT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 });
+        output = `${result.stdout}${result.stderr}`;
+    } catch (cause) {
+        throw new ConvertFailed(`LibreOffice could not convert it: ${errorMessage(cause).split("\n").slice(0, 3).join(" ")}`);
+    }
+    // LibreOffice names the PDF after the source and exits 0 even when it wrote nothing, so the file is the answer.
+    const expected = `${basename(absPath, extname(absPath))}.pdf`;
+    const written = await listDir(outDir);
+    if (!written.includes(expected)) {
+        const said = output.trim().split("\n").slice(-2).join(" ");
+        throw new ConvertFailed(`LibreOffice wrote no PDF${said === "" ? "" : ` (it said: ${said})`}; the file may be damaged or password-protected`);
+    }
+    return join(outDir, expected);
+};
+
+/**
+ * Rasterizes the given pages of `pdf` into `outDir`, each fitted into a `size`-pixel square, and answers each page's
+ * PNG path. The rasterizers name their files differently; the page number is read back off the name either way.
+ */
+export const toPngs = async (tool: Rasterizer, pdf: string, pages: readonly number[], size: number, outDir: string): Promise<Map<number, string>> => {
+    const prefix = join(outDir, "p");
+    try {
+        if (tool === "pdftoppm") {
+            for (const [first, last] of runsOf(pages)) {
+                await run("pdftoppm", ["-png", "-scale-to", String(size), "-f", String(first), "-l", String(last), pdf, prefix], { timeout: RASTER_TIMEOUT_MS });
+            }
+        } else {
+            await run("mutool", ["draw", "-q", "-F", "png", "-w", String(size), "-h", String(size), "-o", `${prefix}-%d.png`, pdf, pages.join(",")], {
+                timeout: RASTER_TIMEOUT_MS,
+            });
+        }
+    } catch (cause) {
+        throw new ConvertFailed(`${tool} could not draw the pages: ${errorMessage(cause).split("\n").slice(0, 3).join(" ")}`);
+    }
+    const drawn = new Map<number, string>();
+    for (const name of await readdir(outDir)) {
+        const match = /^p-0*(\d+)\.png$/.exec(name);
+        if (match !== null) {
+            drawn.set(Number(match[1]), join(outDir, name));
+        }
+    }
+    return drawn;
+};

package/src/lib/render/pages.test.ts

@@ -0,0 +1,38 @@
+import { BadPages, describePages, pagesWithin, parsePages, runsOf } from "./pages.js";
+
+describe("parsePages", () => {
+    test("a page, a range, an open range and a list", () => {
+        expect(parsePages("3")).toEqual([{ from: 3, to: 3 }]);
+        expect(parsePages("1-3")).toEqual([{ from: 1, to: 3 }]);
+        expect(parsePages("7-")).toEqual([{ from: 7, to: undefined }]);
+        expect(parsePages("2, 5,7-9")).toEqual([
+            { from: 2, to: 2 },
+            { from: 5, to: 5 },
+            { from: 7, to: 9 },
+        ]);
+    });
+
+    test("page 0, a backwards range and words are refused with the reason", () => {
+        expect(() => parsePages("0")).toThrow(BadPages);
+        expect(() => parsePages("5-2")).toThrow("pages count from 1, and a range runs forward");
+        expect(() => parsePages("first")).toThrow('--pages takes numbers and ranges like 1-3,5,7-; "first" is neither');
+    });
+});
+
+describe("pagesWithin", () => {
+    test("ranges are clipped to the document, merged, sorted, each page once", () => {
+        expect(pagesWithin(parsePages("4-,2,3-5"), 6)).toEqual([2, 3, 4, 5, 6]);
+        expect(pagesWithin(parsePages("8-10"), 6)).toEqual([]);
+    });
+});
+
+describe("runsOf and describePages", () => {
+    test("consecutive pages form one run, for the rasterizer and for the message", () => {
+        expect(runsOf([1, 2, 3, 5, 7, 8])).toEqual([
+            [1, 3],
+            [5, 5],
+            [7, 8],
+        ]);
+        expect(describePages([1, 2, 3, 5, 7, 8])).toBe("1-3, 5, 7-8");
+    });
+});