@intentic/fileq 1.317.0 → 1.319.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/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;
+    }
+};