@intentic/fileq 1.318.0 → 1.320.0

package/src/lib/check/{pptx.ts → check-pptx.ts}

@@ -250,7 +250,8 @@ const textStyleOf = (drawing: XmlElement, chain: readonly XmlElement[], inherita
     return { listStyles: [...own, ...tail] };
 };
 
-const hundredthsAt = (element: XmlElement | undefined, path: readonly string[], attribute: string): number | undefined => intAttr(childAt(element, ...path), attribute);
+const hundredthsAt = (element: XmlElement | undefined, path: readonly string[], attribute: string): number | undefined =>
+    intAttr(childAt(element, ...path), attribute);
 
 const paragraphsOf = (txBody: XmlElement, style: TextStyle, fontScale: number, spacingReduction: number): Paragraph[] =>
     childrenNamed(txBody, "a:p").map((p) => {
@@ -274,7 +275,10 @@ const paragraphsOf = (txBody: XmlElement, style: TextStyle, fontScale: number, s
                 ...style.listStyles.map((listStyle) => () => intAttr(childAt(listStyle, `a:lvl${level}pPr`, "a:defRPr"), attribute)),
             ]);
         const runSizes = runs.flatMap((run) => intAttr(childNamed(run, "a:rPr"), "sz") ?? []);
-        const size = runSizes.length > 0 ? Math.max(...runSizes) : (intAttr(childNamed(p, "a:endParaRPr"), "sz") ?? inherited("sz") ?? DEFAULT_SIZE_HUNDREDTHS);
+        const size =
+            runSizes.length > 0
+                ? Math.max(...runSizes)
+                : (intAttr(childNamed(p, "a:endParaRPr"), "sz") ?? inherited("sz") ?? DEFAULT_SIZE_HUNDREDTHS);
         const bold = runs.some((run) => childNamed(run, "a:rPr")?.attrs["b"] === "1") || (runs.length > 0 && inherited("b") === 1);
         const spacing = (name: string): number | undefined =>
             firstOf([
@@ -348,7 +352,13 @@ const overflowFindings = (drawing: XmlElement, chain: readonly XmlElement[], box
     if (body.autofit === "grow") {
         // The box grows to fit its text, so the text cannot overflow the box, only the slide.
         return box.y + needed > context.height * 1.02
-            ? [warning("text-overflow", where, `the box grows to fit its text, and about ${plural(estimate.lines, "line")} of ${estimate.sizePt} pt take it past the bottom of the slide ${look}`)]
+            ? [
+                  warning(
+                      "text-overflow",
+                      where,
+                      `the box grows to fit its text, and about ${plural(estimate.lines, "line")} of ${estimate.sizePt} pt take it past the bottom of the slide ${look}`,
+                  ),
+              ]
             : [];
     }
     if (estimate.heightPt <= innerHeight * OVERFLOW_MARGIN) {
@@ -391,7 +401,11 @@ const tableFindings = (frame: XmlElement, box: Box, where: string, context: Slid
             const tcPr = childNamed(cell, "a:tcPr");
             const marginX = (intAttr(tcPr, "marL") ?? DEFAULT_INSET_X) + (intAttr(tcPr, "marR") ?? DEFAULT_INSET_X);
             const marginY = (intAttr(tcPr, "marT") ?? DEFAULT_INSET_Y) + (intAttr(tcPr, "marB") ?? DEFAULT_INSET_Y);
-            const estimate = estimateText(paragraphsOf(txBody, { listStyles: [childNamed(txBody, "a:lstStyle")] }, 1, 0), (cellWidth - marginX) / EMU_PER_PT, true);
+            const estimate = estimateText(
+                paragraphsOf(txBody, { listStyles: [childNamed(txBody, "a:lstStyle")] }, 1, 0),
+                (cellWidth - marginX) / EMU_PER_PT,
+                true,
+            );
             rowHeight = Math.max(rowHeight, estimate.heightPt * EMU_PER_PT + marginY);
         }
         total += rowHeight;
@@ -421,7 +435,11 @@ const referenceFinding = (node: XmlElement, id: string, where: string, context:
     }
     if (relationship.external) {
         return isImage
-            ? warning("linked-image", where, `image is linked from outside the file (${relationship.target}), so it will not show on anyone else's machine; embed it`)
+            ? warning(
+                  "linked-image",
+                  where,
+                  `image is linked from outside the file (${relationship.target}), so it will not show on anyone else's machine; embed it`,
+              )
             : undefined;
     }
     if (context.pkg.has(relationship.target)) {
@@ -452,7 +470,14 @@ const pictureFindings = (picture: XmlElement, box: Box | undefined, where: strin
     }
     const embed = childAt(blipFill, "a:blip")?.attrs["r:embed"];
     const relationship = embed === undefined ? undefined : context.pkg.rels(context.part).get(embed);
-    if (box !== undefined && relationship !== undefined && !relationship.external && context.pkg.has(relationship.target) && box.cx > 0 && box.cy > 0) {
+    if (
+        box !== undefined &&
+        relationship !== undefined &&
+        !relationship.external &&
+        context.pkg.has(relationship.target) &&
+        box.cx > 0 &&
+        box.cy > 0
+    ) {
         context.pictures.push({ where, media: relationship.target, cx: box.cx, cy: box.cy, crop: sides });
     }
     return [];
@@ -553,7 +578,8 @@ const drawingFindings = (drawing: XmlElement, context: SlideContext, grouped: bo
 const layoutsOf = (pkg: OoxmlPackage, slidePart: string): Pick<Inheritance, "layout" | "master"> => {
     const layoutRel = [...pkg.rels(slidePart).values()].find((relationship) => relationship.kind === "slideLayout" && !relationship.external);
     const layout = layoutRel === undefined ? undefined : pkg.xml(layoutRel.target);
-    const masterRel = layoutRel === undefined ? undefined : [...pkg.rels(layoutRel.target).values()].find((relationship) => relationship.kind === "slideMaster");
+    const masterRel =
+        layoutRel === undefined ? undefined : [...pkg.rels(layoutRel.target).values()].find((relationship) => relationship.kind === "slideMaster");
     return { layout, master: masterRel === undefined ? undefined : pkg.xml(masterRel.target) };
 };
 
@@ -561,7 +587,9 @@ const slideFindings = (context: SlideContext, tree: XmlElement): Finding[] => {
     const findings: Finding[] = [];
     const slideWhere = `slide ${context.number}`;
     if (tree.attrs["show"] === "0") {
-        findings.push(warning("hidden-slide", slideWhere, "the slide is hidden, so the slide show skips it; delete it if it is not meant to be delivered"));
+        findings.push(
+            warning("hidden-slide", slideWhere, "the slide is hidden, so the slide show skips it; delete it if it is not meant to be delivered"),
+        );
     }
     const referenced = new Set<string>();
     const background = childAt(tree, "p:cSld", "p:bg");
@@ -588,7 +616,11 @@ export const checkPptx = (bytes: Uint8Array): CheckReport => {
         pkg = openPackage(bytes);
     } catch (cause) {
         if (cause instanceof NotAPackage) {
-            return { format: "pptx", findings: [error("unreadable", "", `${cause.message}: this is not a PowerPoint file (or it is password-protected)`)], notes: [] };
+            return {
+                format: "pptx",
+                findings: [error("unreadable", "", `${cause.message}: this is not a PowerPoint file (or it is password-protected)`)],
+                notes: [],
+            };
         }
         throw cause;
     }
@@ -617,7 +649,13 @@ export const checkPptx = (bytes: Uint8Array): CheckReport => {
         const number = index + 1;
         const relationship = rels.get(slideId.attrs["r:id"] ?? "");
         if (relationship === undefined || relationship.external || !pkg.has(relationship.target)) {
-            findings.push(error("missing-part", `slide ${number}`, "the slide list names a slide that is not in the file; PowerPoint will offer to repair the deck"));
+            findings.push(
+                error(
+                    "missing-part",
+                    `slide ${number}`,
+                    "the slide list names a slide that is not in the file; PowerPoint will offer to repair the deck",
+                ),
+            );
             return;
         }
         const tree = pkg.xml(relationship.target);
@@ -638,4 +676,3 @@ export const checkPptx = (bytes: Uint8Array): CheckReport => {
     findings.push(...stretchFindings(pkg, pictures));
     return { format: "pptx", extent: plural(slideIds.length, "slide"), findings, notes };
 };
-

package/src/lib/check/{xlsx.ts → check-xlsx.ts}

@@ -23,7 +23,8 @@ 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}`);
+const cellRef = (sheet: string, ref: string): string =>
+    /^[A-Za-z_][\w.]*$/.test(sheet) ? `${sheet}!${ref}` : `'${sheet.replaceAll("'", "''")}'!${ref}`;
 
 interface SheetScan {
     readonly errors: Finding[];
@@ -71,9 +72,14 @@ const scanSheet = (sheet: string, xml: string): SheetScan => {
 };
 
 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 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";
+    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,
@@ -86,7 +92,11 @@ const openWorkbook = (bytes: Uint8Array): OoxmlPackage | CheckReport => {
         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: [] };
+            return {
+                format: "xlsx",
+                findings: [error("unreadable", "", `${cause.message}: this is not an Excel file (or it is password-protected)`)],
+                notes: [],
+            };
         }
         throw cause;
     }
@@ -96,7 +106,9 @@ 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`)] : [];
+        return target.includes("#REF!")
+            ? [error("broken-name", "", `the defined name "${name.attrs["name"] ?? "?"}" refers to ${excerpt(target)}, a deleted range`)]
+            : [];
     });
 };
 
@@ -121,7 +133,9 @@ const sheetsFindings = (pkg: OoxmlPackage, main: string, sheets: readonly XmlEle
         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"));
+            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.

package/src/lib/check/check.test.ts

@@ -1,11 +1,24 @@
 import { strToU8 } from "fflate";
-import { deckBytes, field, inlinePicture, para, pdfBytes, pdfPagesBytes, pictureFrame, pngOfSize, tableFrame, textBox, wordBytes, workbookBytes } from "../../testing.js";
-import { checkDocx } from "./docx.js";
+import {
+    deckBytes,
+    field,
+    inlinePicture,
+    para,
+    pdfBytes,
+    pdfPagesBytes,
+    pictureFrame,
+    pngOfSize,
+    tableFrame,
+    textBox,
+    wordBytes,
+    workbookBytes,
+} from "../../testing.js";
+import { checkDocx } from "./check-docx.js";
 import { leftoverText, type CheckReport } from "./finding.js";
-import { checkPdf } from "./pdf.js";
-import { checkPptx } from "./pptx.js";
+import { checkPdf } from "./check-pdf.js";
+import { checkPptx } from "./check-pptx.js";
 import { estimateText, wrappedLines, type Paragraph } from "./text-fit.js";
-import { checkXlsx } from "./xlsx.js";
+import { checkXlsx } from "./check-xlsx.js";
 import { parseXml } from "./xml-tree.js";
 
 // Every checker against a document built with one known defect, and against a clean one, which must come back with
@@ -52,7 +65,9 @@ describe("pptx", () => {
     test("a drawing wholly off the slide is an error, one bleeding past an edge a warning with how far", () => {
         const report = checkPptx(
             deckBytes({
-                slides: [{ drawings: [textBox("Gone", { x: 14, y: 1, w: 2, h: 1 }, ["off"]), textBox("Bleed", { x: 12, y: 1, w: 3, h: 1 }, ["partly"])] }],
+                slides: [
+                    { drawings: [textBox("Gone", { x: 14, y: 1, w: 2, h: 1 }, ["off"]), textBox("Bleed", { x: 12, y: 1, w: 3, h: 1 }, ["partly"])] },
+                ],
             }),
         );
         expect(found(report)).toEqual([
@@ -100,7 +115,10 @@ describe("pptx", () => {
             deckBytes({
                 slides: [
                     {
-                        drawings: [pictureFrame("Gone", { x: 1, y: 1, w: 4, h: 3 }, "rId2"), pictureFrame("Undefined", { x: 6, y: 1, w: 4, h: 3 }, "rId9")],
+                        drawings: [
+                            pictureFrame("Gone", { x: 1, y: 1, w: 4, h: 3 }, "rId2"),
+                            pictureFrame("Undefined", { x: 6, y: 1, w: 4, h: 3 }, "rId9"),
+                        ],
                         rels: { rId2: { type: "image", target: "../media/missing.png" } },
                     },
                 ],
@@ -116,7 +134,12 @@ describe("pptx", () => {
     test("an image linked from outside the file is a warning naming where it points", () => {
         const report = checkPptx(
             deckBytes({
-                slides: [{ drawings: [pictureFrame("Logo", { x: 1, y: 1, w: 4, h: 3 }, "rId2")], rels: { rId2: { type: "image", target: "file:///C:/Users/me/logo.png", external: true } } }],
+                slides: [
+                    {
+                        drawings: [pictureFrame("Logo", { x: 1, y: 1, w: 4, h: 3 }, "rId2")],
+                        rels: { rId2: { type: "image", target: "file:///C:/Users/me/logo.png", external: true } },
+                    },
+                ],
             }),
         );
         expect(found(report)).toEqual([["warning", "linked-image", 'slide 1 · "Logo"']]);
@@ -128,7 +151,10 @@ describe("pptx", () => {
             deckBytes({
                 slides: [
                     {
-                        drawings: [pictureFrame("Wide", { x: 1, y: 1, w: 4, h: 1 }, "rId2"), pictureFrame("Cropped", { x: 6, y: 1, w: 4, h: 3 }, "rId2", { l: 60_000, r: 40_000 })],
+                        drawings: [
+                            pictureFrame("Wide", { x: 1, y: 1, w: 4, h: 1 }, "rId2"),
+                            pictureFrame("Cropped", { x: 6, y: 1, w: 4, h: 3 }, "rId2", { l: 60_000, r: 40_000 }),
+                        ],
                         rels: { rId2: IMAGE },
                     },
                 ],
@@ -147,7 +173,9 @@ describe("pptx", () => {
     test("a picture cropped to its box's proportions is not stretched", () => {
         const report = checkPptx(
             deckBytes({
-                slides: [{ drawings: [pictureFrame("Banner", { x: 1, y: 1, w: 4, h: 1.5 }, "rId2", { t: 25_000, b: 25_000 })], rels: { rId2: IMAGE } }],
+                slides: [
+                    { drawings: [pictureFrame("Banner", { x: 1, y: 1, w: 4, h: 1.5 }, "rId2", { t: 25_000, b: 25_000 })], rels: { rId2: IMAGE } },
+                ],
                 media: { "image1.png": pngOfSize(400, 300) },
             }),
         );
@@ -155,7 +183,8 @@ describe("pptx", () => {
     });
 
     test("text that cannot fit its box is a warning with the estimate, pointing at render", () => {
-        const long = "This is a very long sentence that will surely not fit in a small box of three inches at twenty four points, and it goes on and on.";
+        const long =
+            "This is a very long sentence that will surely not fit in a small box of three inches at twenty four points, and it goes on and on.";
         const report = checkPptx(
             deckBytes({
                 slides: [
@@ -177,7 +206,10 @@ describe("pptx", () => {
                     {
                         drawings: [
                             textBox("Fits", { x: 1, y: 1, w: 6, h: 1.2 }, ["Two lines of", "comfortable text"], { size: 24 }),
-                            textBox("Grows", { x: 1, y: 3, w: 3, h: 0.5 }, ["A sentence long enough to need three or four lines here."], { size: 18, autofit: "grow" }),
+                            textBox("Grows", { x: 1, y: 3, w: 3, h: 0.5 }, ["A sentence long enough to need three or four lines here."], {
+                                size: 18,
+                                autofit: "grow",
+                            }),
                         ],
                     },
                 ],
@@ -187,9 +219,14 @@ describe("pptx", () => {
     });
 
     test("shrink-on-overflow says PowerPoint shows it overflowing until edited", () => {
-        const long = "A paragraph much too long for its box, which PowerPoint only shrinks once somebody edits the text and LibreOffice shrinks at once.";
-        const report = checkPptx(deckBytes({ slides: [{ drawings: [textBox("Body", { x: 1, y: 1, w: 3, h: 0.6 }, [long], { size: 24, autofit: "shrink" })] }] }));
-        expect(messageOf(report, "text-overflow")).toContain("shrink-on-overflow is on, so LibreOffice shrinks it but PowerPoint shows it overflowing until the text is edited");
+        const long =
+            "A paragraph much too long for its box, which PowerPoint only shrinks once somebody edits the text and LibreOffice shrinks at once.";
+        const report = checkPptx(
+            deckBytes({ slides: [{ drawings: [textBox("Body", { x: 1, y: 1, w: 3, h: 0.6 }, [long], { size: 24, autofit: "shrink" })] }] }),
+        );
+        expect(messageOf(report, "text-overflow")).toContain(
+            "shrink-on-overflow is on, so LibreOffice shrinks it but PowerPoint shows it overflowing until the text is edited",
+        );
     });
 
     test("a table whose rows run past the bottom of the slide is a warning", () => {
@@ -233,7 +270,14 @@ describe("docx", () => {
     test("a well-made document has nothing to report", () => {
         const report = checkDocx(
             wordBytes({
-                body: [para("Report", "berschrift1"), para("The body of the report."), '<w:p><w:bookmarkStart w:id="0" w:name="results"/><w:bookmarkEnd w:id="0"/></w:p>', '<w:p><w:hyperlink w:anchor="results"><w:r><w:t>see results</w:t></w:r></w:hyperlink></w:p>', inlinePicture("rId5", 6, 3), field("PAGE", "1")],
+                body: [
+                    para("Report", "berschrift1"),
+                    para("The body of the report."),
+                    '<w:p><w:bookmarkStart w:id="0" w:name="results"/><w:bookmarkEnd w:id="0"/></w:p>',
+                    '<w:p><w:hyperlink w:anchor="results"><w:r><w:t>see results</w:t></w:r></w:hyperlink></w:p>',
+                    inlinePicture("rId5", 6, 3),
+                    field("PAGE", "1"),
+                ],
                 rels: { rId5: DOC_IMAGE },
                 media: { "image1.png": pngOfSize(600, 300) },
             }),
@@ -243,13 +287,21 @@ describe("docx", () => {
     });
 
     test("a link to a bookmark that is not there is an error, located by its paragraph", () => {
-        const report = checkDocx(wordBytes({ body: [para("Intro", "berschrift1"), '<w:p><w:hyperlink w:anchor="nowhere"><w:r><w:t>see section</w:t></w:r></w:hyperlink></w:p>'] }));
+        const report = checkDocx(
+            wordBytes({
+                body: [para("Intro", "berschrift1"), '<w:p><w:hyperlink w:anchor="nowhere"><w:r><w:t>see section</w:t></w:r></w:hyperlink></w:p>'],
+            }),
+        );
         expect(found(report)).toEqual([["error", "broken-link", 'paragraph 2 · "see section"']]);
-        expect(messageOf(report, "broken-link")).toBe('the link "see section" points to bookmark "nowhere", which is not in the document, so clicking it goes nowhere');
+        expect(messageOf(report, "broken-link")).toBe(
+            'the link "see section" points to bookmark "nowhere", which is not in the document, so clicking it goes nowhere',
+        );
     });
 
     test("a cross-reference to a missing bookmark, and a field showing Word's error, are errors said once", () => {
-        const report = checkDocx(wordBytes({ body: [field("PAGEREF _Ref999 \\h", "3"), field("REF _Ref123 \\h", "Error! Reference source not found.")] }));
+        const report = checkDocx(
+            wordBytes({ body: [field("PAGEREF _Ref999 \\h", "3"), field("REF _Ref123 \\h", "Error! Reference source not found.")] }),
+        );
         expect(found(report)).toEqual([
             ["error", "broken-reference", 'paragraph 1 · "3"'],
             ["error", "field-error", 'paragraph 2 · "Error! Reference source not found."'],
@@ -281,7 +333,9 @@ describe("docx", () => {
             ["error", "missing-image", "paragraph 2"],
             ["warning", "wide-image", "paragraph 1"],
         ]);
-        expect(messageOf(report, "wide-image")).toBe("a picture is 9 in wide in a 6.5 in text column, so it runs into the margin or is cut off; scale it to fit");
+        expect(messageOf(report, "wide-image")).toBe(
+            "a picture is 9 in wide in a 6.5 in text column, so it runs into the margin or is cut off; scale it to fit",
+        );
     });
 
     test("what a draft leaves behind: tracked changes, comments, a control showing its prompt, filler text", () => {
@@ -289,7 +343,7 @@ describe("docx", () => {
             wordBytes({
                 body: [
                     '<w:p><w:ins w:id="1" w:author="a"><w:r><w:t>new words</w:t></w:r></w:ins></w:p>',
-                    '<w:sdt><w:sdtPr><w:showingPlcHdr/></w:sdtPr><w:sdtContent><w:p><w:r><w:t>Click or tap here to enter text.</w:t></w:r></w:p></w:sdtContent></w:sdt>',
+                    "<w:sdt><w:sdtPr><w:showingPlcHdr/></w:sdtPr><w:sdtContent><w:p><w:r><w:t>Click or tap here to enter text.</w:t></w:r></w:p></w:sdtContent></w:sdt>",
                     para("Lorem ipsum dolor sit amet."),
                 ],
                 comments: ["check this figure"],
@@ -316,7 +370,9 @@ const cell = (ref: string, inner: string, type?: string): string => `<c r="${ref
 
 describe("xlsx", () => {
     test("a workbook of values and computed formulas has nothing to report", () => {
-        const report = checkXlsx(workbookBytes([{ name: "Sheet1", rows: `<row r="1">${cell("A1", "<v>1</v>")}${cell("B1", "<f>A1*2</f><v>2</v>")}</row>` }]));
+        const report = checkXlsx(
+            workbookBytes([{ name: "Sheet1", rows: `<row r="1">${cell("A1", "<v>1</v>")}${cell("B1", "<f>A1*2</f><v>2</v>")}</row>` }]),
+        );
         expect(report.extent).toBe("1 sheet");
         expect(report.findings).toEqual([]);
     });
@@ -336,7 +392,9 @@ describe("xlsx", () => {
         const rows = `<row r="1">${cell("A1", "<v>1</v>")}${cell("B1", "<f>A1+1</f>")}${cell("C1", "<f>A1+2</f>")}</row>`;
         const plain = checkXlsx(workbookBytes([{ name: "Data", rows }]));
         expect(found(plain)).toEqual([["warning", "formula-uncached", "Data"]]);
-        expect(messageOf(plain, "formula-uncached")).toContain("2 formulas saved with no value (B1, C1): Excel, LibreOffice and Google Sheets compute them on open");
+        expect(messageOf(plain, "formula-uncached")).toContain(
+            "2 formulas saved with no value (B1, C1): Excel, LibreOffice and Google Sheets compute them on open",
+        );
         const flagged = checkXlsx(workbookBytes([{ name: "Data", rows }], { calcPr: '<calcPr fullCalcOnLoad="1"/>' }));
         expect(messageOf(flagged, "formula-uncached")).toContain("the workbook asks to be recalculated on open");
     });
@@ -365,12 +423,19 @@ describe("pdf", () => {
     });
 
     test("a blank page is an error; a page with only a drawing is not blank", async () => {
-        const report = await checkPdf(pdfPagesBytes([{ content: "BT /F1 12 Tf 72 720 Td (Cover) Tj ET" }, { content: "" }, { content: "0 0 1 rg 10 10 100 100 re f" }]));
+        const report = await checkPdf(
+            pdfPagesBytes([{ content: "BT /F1 12 Tf 72 720 Td (Cover) Tj ET" }, { content: "" }, { content: "0 0 1 rg 10 10 100 100 re f" }]),
+        );
         expect(found(report)).toEqual([["error", "blank-page", "page 2"]]);
     });
 
     test("text in a font the file does not carry is a warning; the fourteen standard fonts are not", async () => {
-        const report = await checkPdf(pdfPagesBytes([{ content: "BT /F1 12 Tf 72 720 Td (Hello) Tj ET", font: "Calibri" }, { content: "BT /F1 12 Tf 72 720 Td (Again) Tj ET", font: "Calibri" }]));
+        const report = await checkPdf(
+            pdfPagesBytes([
+                { content: "BT /F1 12 Tf 72 720 Td (Hello) Tj ET", font: "Calibri" },
+                { content: "BT /F1 12 Tf 72 720 Td (Again) Tj ET", font: "Calibri" },
+            ]),
+        );
         expect(found(report)).toEqual([["warning", "font-not-embedded", "page 1, 2"]]);
         expect(messageOf(report, "font-not-embedded")).toContain("text is set in Calibri, which the file does not carry");
     });
@@ -384,7 +449,12 @@ describe("pdf", () => {
 
     test("a link to a named destination the file does not define is an error", async () => {
         const report = await checkPdf(
-            pdfPagesBytes([{ content: "BT /F1 12 Tf 72 720 Td (See results) Tj ET", extra: "/Annots [<< /Type /Annot /Subtype /Link /Rect [72 700 200 730] /Dest (results) >>]" }]),
+            pdfPagesBytes([
+                {
+                    content: "BT /F1 12 Tf 72 720 Td (See results) Tj ET",
+                    extra: "/Annots [<< /Type /Annot /Subtype /Link /Rect [72 700 200 730] /Dest (results) >>]",
+                },
+            ]),
         );
         expect(found(report)).toEqual([["error", "broken-link", "page 1"]]);
     });
@@ -422,7 +492,9 @@ describe("xml tree", () => {
     });
 
     test("entities decode, CDATA is text, whitespace is kept only inside a text element", () => {
-        const tree = parseXml('<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">\n  <w:t> A &amp; B </w:t><w:t><![CDATA[<raw>]]></w:t>\n</w:p>');
+        const tree = parseXml(
+            '<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">\n  <w:t> A &amp; B </w:t><w:t><![CDATA[<raw>]]></w:t>\n</w:p>',
+        );
         expect(tree.children).toEqual([
             { name: "w:t", attrs: {}, children: [" A & B "] },
             { name: "w:t", attrs: {}, children: ["<raw>"] },

package/src/lib/check/check.ts

@@ -1,11 +1,11 @@
 import { readFile, stat } from "node:fs/promises";
 import { errorMessage, isMissing } from "@intentic/base/errors";
 import { claimedFormat, type Format } from "../formats.js";
-import { checkDocx } from "./docx.js";
+import { checkDocx } from "./check-docx.js";
 import type { CheckReport } from "./finding.js";
-import { checkPdf } from "./pdf.js";
-import { checkPptx } from "./pptx.js";
-import { checkXlsx } from "./xlsx.js";
+import { checkPdf } from "./check-pdf.js";
+import { checkPptx } from "./check-pptx.js";
+import { checkXlsx } from "./check-xlsx.js";
 
 // `fileq check`'s routing: which formats have a checker, and the one read of the file every checker works from.
 

package/src/lib/content-cache.ts

@@ -0,0 +1,58 @@
+import { join } from "node:path";
+import { toolHome } from "@intentic/agent-cli/env";
+import type { DerivedDoc } from "./derivers/deriver.js";
+import { DERIVED_DIR, ignoreShadowsInGit, isFresh, parseSidecarFront, readSidecar, sidecarBody, writeDerived, type DerivedEntry } from "./sidecar.js";
+
+// Renderings keyed by what they are a function of, the source's sha256 and the deriver stamp, never by its path: the
+// same bytes read again (the same file, a copy or a move, a download, a git blob) answer from here without a deriver.
+// Kept in the workspace's derived tree when there is a workspace, so its .gitignore covers them, else in the per-user
+// cache. A cache that cannot be read or written costs the speed-up, never the read.
+
+export const contentCacheDir = (workspaceRoot: string | undefined): string =>
+    workspaceRoot === undefined ? join(toolHome("fileq"), "by-hash") : join(workspaceRoot, DERIVED_DIR, ".by-hash");
+
+// The stamp made safe for a file name (`docx v2` → `docx-v2`); a hit is checked against the entry's own front matter.
+export const contentCachePathFor = (workspaceRoot: string | undefined, sourceSha: string, deriverStamp: string): string =>
+    join(contentCacheDir(workspaceRoot), `${sourceSha}.${deriverStamp.replaceAll(/[^A-Za-z0-9.+-]/g, "-")}.md`);
+
+export interface CachedRendering {
+    readonly path: string;
+    readonly doc: DerivedDoc;
+    readonly derivedAt: Date;
+}
+
+/** The stored rendering of these bytes by this deriver; undefined when there is none, or none that still matches. */
+export const readCachedRendering = async (
+    workspaceRoot: string | undefined,
+    sourceSha: string,
+    deriverStamp: string,
+): Promise<CachedRendering | undefined> => {
+    const path = contentCachePathFor(workspaceRoot, sourceSha, deriverStamp);
+    const content = await readSidecar(path);
+    if (content === undefined || !isFresh(content, sourceSha, deriverStamp)) {
+        return undefined;
+    }
+    const front = parseSidecarFront(content);
+    const derivedAt = new Date(front.derivedAt ?? Number.NaN);
+    if (Number.isNaN(derivedAt.getTime())) {
+        return undefined;
+    }
+    const body = sidecarBody(content);
+    // writeDerived ends a non-empty body with one newline of its own.
+    const markdown = body.endsWith("\n") ? body.slice(0, -1) : body;
+    return { path, doc: { markdown, title: front.title, notes: [...front.notes] }, derivedAt };
+};
+
+/** Stores a rendering under its content key; answers the entry's path, or undefined when it could not be written. */
+export const cacheRendering = async (workspaceRoot: string | undefined, entry: Omit<DerivedEntry, "source">): Promise<string | undefined> => {
+    try {
+        const written = await writeDerived(contentCachePathFor(workspaceRoot, entry.sourceSha, entry.deriverStamp), entry);
+        if (workspaceRoot !== undefined) {
+            await ignoreShadowsInGit(workspaceRoot);
+        }
+        return written.path;
+    } catch {
+        // allow(silent-catch): an unwritable cache costs the next read its speed-up, never this read its rendering.
+        return undefined;
+    }
+};