@intentic/fileq 1.317.0

package/src/lib/derivers/odt.ts

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { unzipSync } from "fflate";
+import { bodyOf, parseHtml } from "@intentic/webq/dom";
+import { renderMarkdown } from "@intentic/webq/markdown";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { attributeOf, decodeEntities } from "../xml.js";
+
+// ODF's content.xml is rewritten tag-for-tag into HTML and handed to webq's writer, the same road docx takes through
+// mammoth, so an .odt and .docx of the same letter render the same markdown.
+// A tag-name substitution over well-formed XML, no parser needed to rename elements; every namespaced tag the table
+// doesn't name is unwrapped, keeping its text but dropping the tag.
+
+// ODF element to HTML element; an empty value is a void marker to drop, since its text is nothing.
+const TAG: Record<string, string> = {
+    "text:p": "p",
+    "text:list": "ul",
+    "text:list-item": "li",
+    "text:list-header": "li",
+    "text:span": "span",
+    "text:a": "a",
+    "text:line-break": "br",
+    "text:note-citation": "sup",
+    "table:table": "table",
+    "table:table-header-rows": "thead",
+    "table:table-row": "tr",
+    "table:table-cell": "td",
+    "table:covered-table-cell": "td", // a merged-away cell: an empty td keeps the columns aligned
+    "table:table-column": "col",
+    "table:table-columns": "colgroup",
+};
+
+// Subtrees that aren't the document's text: comments, tracked changes, drawing metadata, TOC machinery.
+const DROP_SUBTREE = [
+    "office:annotation",
+    "text:tracked-changes",
+    "draw:frame",
+    "text:table-of-content-source",
+    "text:index-title-template",
+    "text:alphabetical-index-source",
+];
+
+const dropSubtrees = (xml: string): string =>
+    DROP_SUBTREE.reduce((text, tag) => text.replaceAll(new RegExp(`<${tag}\\b[^>]*?(?:/>|>[\\s\\S]*?</${tag}>)`, "g"), ""), xml);
+
+/** content.xml's <office:text> body as the HTML webq's writer understands; exported for tests. */
+export const odfToHtml = (xml: string): string => {
+    const start = xml.indexOf("<office:text");
+    const end = xml.lastIndexOf("</office:text>");
+    const body = dropSubtrees(start === -1 || end === -1 ? xml : xml.slice(start, end));
+    return (
+        body
+            // Headings carry level as an attribute, so tag and level are rewritten together (headings never nest).
+            .replaceAll(/<text:h\b([^>]*)>([\s\S]*?)<\/text:h>/g, (_, attributes: string, inner: string) => {
+                const level = Math.min(6, Math.max(1, Number(attributeOf(attributes, "text:outline-level") ?? "1") || 1));
+                return `<h${level}>${inner}</h${level}>`;
+            })
+            // ODF writes runs of spaces/tabs as elements, since XML would otherwise collapse them.
+            .replaceAll(/<text:s\b([^>]*)\/>/g, (_, attributes: string) => " ".repeat(Number(attributeOf(attributes, "text:c") ?? "1") || 1))
+            .replaceAll(/<text:tab\b[^>]*\/>/g, " ")
+            // Namespaced tags: mapped ones become their HTML, the rest are unwrapped.
+            .replaceAll(
+                /<(\/?)([a-zA-Z0-9]+:[a-zA-Z0-9-]+)((?:\s[^>]*?)?)(\/?)>/g,
+                (_, close: string, name: string, attributes: string, selfClosing: string) => {
+                    const mapped = TAG[name];
+                    if (mapped === undefined) {
+                        return "";
+                    }
+                    if (close === "/") {
+                        return `</${mapped}>`;
+                    }
+                    if (mapped === "a") {
+                        const href = attributeOf(attributes, "xlink:href");
+                        return href === undefined ? "<a>" : `<a href="${href.replaceAll('"', "&quot;")}">`;
+                    }
+                    return selfClosing === "/" && mapped !== "br" && mapped !== "col" ? `<${mapped}></${mapped}>` : `<${mapped}>`;
+                },
+            )
+            // A list item's single paragraph is unwrapped, since <p> inside <li> would render as bullet then text
+            // below.
+            .replaceAll(/<li>\s*<p>/g, "<li>")
+            .replaceAll(/<\/p>\s*<\/li>/g, "</li>")
+    );
+};
+
+export const odtDeriver: Deriver = {
+    name: "odt",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const zip = unzipSync(new Uint8Array(await readFile(absPath)));
+        const decoder = new TextDecoder();
+        const content = zip["content.xml"];
+        if (content === undefined) {
+            return { markdown: "", notes: ["no content.xml in this OpenDocument container"] };
+        }
+        const meta = zip["meta.xml"];
+        const titleMatch = meta === undefined ? null : /<dc:title>([\s\S]*?)<\/dc:title>/.exec(decoder.decode(meta));
+        const title = titleMatch?.[1] === undefined || titleMatch[1].trim() === "" ? undefined : decodeEntities(titleMatch[1].trim());
+        const body = bodyOf(parseHtml(`<html><body>${odfToHtml(decoder.decode(content))}</body></html>`));
+        return { markdown: body === undefined ? "" : renderMarkdown(body), title, notes: [] };
+    },
+};

package/src/lib/derivers/pdf-furniture.test.ts

@@ -0,0 +1,60 @@
+import { stripRunningFurniture } from "./pdf-furniture.js";
+
+const WORDS = ["", "alpha", "beta", "gamma", "delta", "epsilon"];
+
+// Page n of a printed RFC: body text between the header and footer it repeats on every page.
+const page = (n: number, body: string): string =>
+    [
+        "RFC 9110 HTTP Semantics June 2022",
+        body,
+        `More of the ${WORDS[n]} part.`,
+        `The last line of ${WORDS[n]}.`,
+        `Fielding, et al. Standards Track [Page ${n}]`,
+    ].join("\n");
+
+describe("stripRunningFurniture", () => {
+    test("removes a running header and a numbered footer, keeping every body line", () => {
+        const pages = [1, 2, 3, 4, 5].map((n) => page(n, `Body of ${WORDS[n]}.`));
+        const { pages: kept, removed, example } = stripRunningFurniture(pages);
+        expect(removed).toBe(10);
+        expect(example).toBe("RFC 9110 HTTP Semantics June 2022");
+        expect(kept[2]).toBe("Body of gamma.\nMore of the gamma part.\nThe last line of gamma.");
+    });
+
+    test("removes bare page numbers only when they count with the pages", () => {
+        const counted = ["alpha", "beta", "gamma", "delta"].map((word, index) => `${word} one\n${word} two\n${word} three\n${index + 3}`);
+        expect(stripRunningFurniture(counted).pages[0]).toBe("alpha one\nalpha two\nalpha three");
+        // A table whose last value happens to sit at the page edge is data, not a folio.
+        const values = ["alpha", "beta", "gamma", "delta"].map((word, index) => `${word} one\n${word} two\n${word} three\n${[42, 17, 42, 9][index]}`);
+        expect(stripRunningFurniture(values).removed).toBe(0);
+    });
+
+    test("removes self-describing page numbers even where nothing else recurs", () => {
+        const pages = ["a", "b", "c", "d"].map((word, index) => `${word} first\n${word} middle\n${word} last\n- ${index + 1} -`);
+        expect(stripRunningFurniture(pages).pages.every((text) => !text.includes("-"))).toBe(true);
+    });
+
+    test("leaves short documents and non-recurring edge lines alone", () => {
+        const short = [1, 2, 3].map((n) => page(n, "body"));
+        expect(stripRunningFurniture(short)).toEqual({ pages: short, removed: 0, example: undefined });
+        const distinct = ["One", "Two", "Three", "Four"].map((word) => `${word} heading\n${word} body\n${word} more\nclosing ${word}`);
+        expect(stripRunningFurniture(distinct).removed).toBe(0);
+        // The same line at the top of some pages and the bottom of others is running at neither edge.
+        const wandering = ["a", "b", "c", "d"].map((word, index) =>
+            index % 2 === 0 ? `See also\n${word} x\n${word} y\n${word} z` : `${word} x\n${word} y\n${word} z\nSee also`,
+        );
+        expect(stripRunningFurniture(wandering).removed).toBe(0);
+        // Numbered content that does not count with the pages is not a running line.
+        const questions = [3, 7, 8, 12].map((n) => `Question ${n}\nWhat is ${n} squared?\nShow ${n} steps.\nAnswer ${n}: ____`);
+        expect(stripRunningFurniture(questions).removed).toBe(0);
+    });
+
+    test("a page holding only furniture comes back empty, and the others keep their places", () => {
+        const pages = [1, 2, 3, 4, 5].map((n) => page(n, `Body of ${WORDS[n]}.`));
+        pages[3] = "RFC 9110 HTTP Semantics June 2022\nFielding, et al. Standards Track [Page 4]";
+        const { pages: kept } = stripRunningFurniture(pages);
+        expect(kept).toHaveLength(5);
+        expect(kept[3]).toBe("");
+        expect(kept[4]).toBe("Body of epsilon.\nMore of the epsilon part.\nThe last line of epsilon.");
+    });
+});

package/src/lib/derivers/pdf-furniture.ts

@@ -0,0 +1,121 @@
+// Running headers, footers and page numbers: the lines a printed document repeats on every page, which cost tokens on
+// each one and split the text they interrupt. Adapted from docurip's PDF text cleaner (MIT,
+// https://github.com/MokuDev/docurip), keeping only its structural rules. Its footnote and "copyright"-line removal
+// delete content, so they are left out.
+// A line is furniture when it sits near a page edge AND recurs at that same edge on most pages (verbatim, or with its
+// numbers counting with the pages), or it is a page number. Content is never judged by what it says.
+
+// How many non-blank lines at each edge of a page can be furniture.
+const EDGE_LINES = 3;
+// Share of pages an edge line must recur on. Below MIN_PAGES there is too little evidence to call anything running.
+const RECUR_SHARE = 0.6;
+const MIN_PAGES = 4;
+
+// A bare number is only a page number when it counts with the pages (see folioOffset); these shapes say so themselves.
+const PAGE_NUMBER = [
+    /^page\s+\d{1,4}(?:\s+of\s+\d{1,4})?$/i, // Page 7, Page 7 of 90
+    /^\d{1,4}\s*(?:of|\/)\s*\d{1,4}$/i, // 7 of 90, 7/90
+    /^[-–—]\s*\d{1,4}\s*[-–—]$/, // - 7 -
+];
+
+export interface Destripped {
+    readonly pages: string[];
+    /** Lines removed, summed over every page. */
+    readonly removed: number;
+    /** The most frequent running line, for the note: a reader should see what was taken. */
+    readonly example: string | undefined;
+}
+
+// Two signatures per line: its exact text (a title, a date that never changes), and its text with every number
+// rewritten as its offset from the page index, so "Page 7" on the seventh page and "Page 8" on the eighth agree.
+// Blanking digits outright would also match "Question 3" and "Question 4", which are content.
+const signaturesOf = (line: string, page: number): string[] => {
+    const exact = line.replaceAll(/\s+/g, " ").trim().toLowerCase();
+    return [`=${exact}`, `~${exact.replaceAll(/\d+/g, (n) => `#${Number(n) - page}`)}`];
+};
+
+interface Edges {
+    readonly top: number[];
+    readonly bottom: number[];
+}
+
+const edgesOf = (lines: readonly string[]): Edges => {
+    const filled = lines.flatMap((line, index) => (line.trim() === "" ? [] : [index]));
+    // At most half a page's lines sit in each edge zone, so a line is a header or a footer, never both.
+    const edge = Math.min(EDGE_LINES, Math.floor(filled.length / 2));
+    return edge === 0 ? { top: [], bottom: [] } : { top: filled.slice(0, edge), bottom: filled.slice(-edge) };
+};
+
+// Headers and footers are counted apart: a line is running only where it recurs at the same edge.
+const recurringAt = (split: readonly string[][], side: keyof Edges, needed: number): Set<string> => {
+    const recurrence = new Map<string, number>();
+    for (const [page, lines] of split.entries()) {
+        // A signature counts once per page, however many edge lines carry it.
+        for (const signature of new Set(edgesOf(lines)[side].flatMap((index) => signaturesOf(lines[index] ?? "", page)))) {
+            recurrence.set(signature, (recurrence.get(signature) ?? 0) + 1);
+        }
+    }
+    // A bare number is folioOffset's call, so a data column's repeated value is not caught here.
+    return new Set(
+        [...recurrence].filter(([signature, count]) => count >= needed && !/^[=~]#?-?\d+$/.test(signature)).map(([signature]) => signature),
+    );
+};
+
+const BARE_NUMBER = /^\d{1,4}$/;
+
+// The offset between page index and printed number that most pages' bare edge numbers agree on, when enough do.
+// A table's last value at a page edge does not count with the pages, so it never matches.
+const folioOffset = (split: readonly string[][], needed: number): number | undefined => {
+    const votes = new Map<number, number>();
+    split.forEach((lines, page) => {
+        const offsets = new Set(
+            [...edgesOf(lines).top, ...edgesOf(lines).bottom]
+                .map((index) => (lines[index] ?? "").trim())
+                .filter((line) => BARE_NUMBER.test(line))
+                .map((line) => Number(line) - page),
+        );
+        for (const offset of offsets) {
+            votes.set(offset, (votes.get(offset) ?? 0) + 1);
+        }
+    });
+    const [offset, count] = [...votes].toSorted((a, b) => b[1] - a[1])[0] ?? [0, 0];
+    return count >= needed ? offset : undefined;
+};
+
+/** Strips running headers, footers and page numbers from per-page text. Pages keep their count and order. */
+export const stripRunningFurniture = (pages: readonly string[]): Destripped => {
+    if (pages.length < MIN_PAGES) {
+        return { pages: [...pages], removed: 0, example: undefined };
+    }
+    const split = pages.map((page) => page.split("\n"));
+    const needed = Math.ceil(pages.length * RECUR_SHARE);
+    const headers = recurringAt(split, "top", needed);
+    const footers = recurringAt(split, "bottom", needed);
+    const offset = folioOffset(split, needed);
+    const seen = new Map<string, number>();
+    let removed = 0;
+    const out = split.map((lines, page) => {
+        const { top, bottom } = edgesOf(lines);
+        const furniture =
+            (running: Set<string>) =>
+            (index: number): boolean => {
+                const line = (lines[index] ?? "").trim();
+                const folio = offset !== undefined && BARE_NUMBER.test(line) && Number(line) - page === offset;
+                return folio || signaturesOf(line, page).some((signature) => running.has(signature)) || PAGE_NUMBER.some((shape) => shape.test(line));
+            };
+        const drop = new Set([...top.filter(furniture(headers)), ...bottom.filter(furniture(footers))]);
+        for (const index of drop) {
+            const line = (lines[index] ?? "").trim();
+            if (!/^\d+$/.test(line)) {
+                seen.set(line, (seen.get(line) ?? 0) + 1);
+            }
+        }
+        removed += drop.size;
+        return lines
+            .filter((_, index) => !drop.has(index))
+            .join("\n")
+            .trim();
+    });
+    const example = [...seen].toSorted((a, b) => b[1] - a[1])[0]?.[0];
+    return { pages: out, removed, example };
+};

package/src/lib/derivers/pdf.ts

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { extractText, getDocumentProxy, getMeta } from "unpdf";
+import { onPath } from "../tools.js";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { stripRunningFurniture } from "./pdf-furniture.js";
+
+// PDF text layer, per page, via unpdf's serverless pdf.js build (no worker, canvas or DOM shims needed for text
+// extraction).
+// A scan with no text layer is rasterised and OCR'd when tesseract is on the image, noted as recognised rather than
+// exact; otherwise the sidecar says so instead of an empty page.
+// Either way, the deterministic tier never guesses at pixels.
+
+// Below this many chars per page, the text layer is furniture, not content: a scan with a vestigial layer.
+const SCAN_THRESHOLD_CHARS_PER_PAGE = 24;
+
+// OCR costs seconds per page and runs unasked in the sweep, so a long scan gets its first pages and a note.
+const MAX_OCR_PAGES = 20;
+const OCR_DPI = "200";
+
+const run = promisify(execFile);
+
+/** Whether this image can recognise a scan: both the rasteriser and the recogniser on PATH. */
+export const ocrAvailable = (): boolean => onPath("tesseract") && onPath("pdftoppm");
+
+const recognisePages = async (absPath: string, totalPages: number): Promise<string[]> => {
+    const dir = await mkdtemp(join(tmpdir(), "fileq-ocr-"));
+    try {
+        await run("pdftoppm", ["-r", OCR_DPI, "-png", "-f", "1", "-l", String(Math.min(totalPages, MAX_OCR_PAGES)), absPath, join(dir, "page")], {
+            timeout: 120_000,
+        });
+        const images = (await readdir(dir)).filter((name) => name.endsWith(".png")).toSorted();
+        const pages: string[] = [];
+        for (const image of images) {
+            const { stdout } = await run("tesseract", [join(dir, image), "stdout", "-l", "eng"], { timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+            pages.push(stdout.replaceAll(/[ \t]+/g, " ").trim());
+        }
+        return pages;
+    } finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+};
+
+const pagesToMarkdown = (pages: readonly string[]): string =>
+    pages.length === 1
+        ? (pages[0] ?? "")
+        : pages.map((page, index) => `## Page ${index + 1}\n\n${page === "" ? "(no text on this page)" : page}`).join("\n\n");
+
+// Every stripped line is named in a note, since a reader comparing against the page image should know what went.
+const furnitureNotes = (removed: number, example: string | undefined): string[] =>
+    removed === 0
+        ? []
+        : [
+              `removed ${removed} running header, footer and page-number line${removed === 1 ? "" : "s"}${example === undefined ? "" : ` (such as "${example}")`}`,
+          ];
+
+const withoutFurniture = (pages: readonly string[]): { markdown: string; notes: string[] } => {
+    const { pages: kept, removed, example } = stripRunningFurniture(pages);
+    return { markdown: pagesToMarkdown(kept), notes: furnitureNotes(removed, example) };
+};
+
+export const pdfDeriver: Deriver = {
+    // The stamp names OCR capability, since a sidecar written before tesseract was available must read as stale now
+    // that it's here.
+    // A static name would leave a pre-OCR sidecar looking current forever.
+    get name(): string {
+        return ocrAvailable() ? "pdf+ocr" : "pdf";
+    },
+    version: 2,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const pdf = await getDocumentProxy(new Uint8Array(await readFile(absPath)));
+        const { totalPages, text } = await extractText(pdf, { mergePages: false });
+        const meta = await getMeta(pdf).catch(() => undefined);
+        const info = meta?.info as Record<string, unknown> | undefined;
+        const title = typeof info?.["Title"] === "string" && info["Title"] !== "" ? info["Title"] : undefined;
+        const pages = text.map((page) => page.replaceAll(/[ \t]+/g, " ").trim());
+        const totalChars = pages.reduce((sum, page) => sum + page.length, 0);
+        if (totalChars < SCAN_THRESHOLD_CHARS_PER_PAGE * totalPages) {
+            const plural = totalPages === 1 ? "" : "s";
+            if (!ocrAvailable()) {
+                return {
+                    markdown: "",
+                    title,
+                    notes: [`no usable text layer across ${totalPages} page${plural} (a scan?): OCR is not part of this tier`],
+                };
+            }
+            const recognised = await recognisePages(absPath, totalPages);
+            const notes = [
+                `scanned: text recognised by OCR (tesseract) on ${recognised.length} of ${totalPages} page${plural} — recognised, not exact; check figures against the page image`,
+            ];
+            if (totalPages > MAX_OCR_PAGES) {
+                notes.push(`OCR stops at ${MAX_OCR_PAGES} pages: run tesseract over the rest yourself if they matter`);
+            }
+            const { markdown, notes: stripped } = withoutFurniture(recognised);
+            return { markdown, title, notes: [...notes, ...stripped] };
+        }
+        return { title, ...withoutFurniture(pages) };
+    },
+};

package/src/lib/derivers/pptx.ts

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import { unzipSync } from "fflate";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { decodeEntities } from "../xml.js";
+
+/* Presentations: text runs out of the OOXML slide parts, one `## Slide N` section each. */
+
+const SLIDE_PART = /^ppt\/slides\/slide(\d+)\.xml$/;
+const NOTES_PART = /^ppt\/notesSlides\/notesSlide(\d+)\.xml$/;
+
+// One slide part's XML → its paragraphs: `<a:t>` runs joined within each `<a:p>`, empties dropped.
+export const slideParagraphs = (xml: string): string[] =>
+    [...xml.matchAll(/<a:p\b[\s\S]*?<\/a:p>/g)]
+        .map((paragraph) =>
+            [...paragraph[0].matchAll(/<a:t[^>]*>([\s\S]*?)<\/a:t>/g)]
+                .map((run) => decodeEntities(run[1] ?? ""))
+                .join("")
+                .trim(),
+        )
+        .filter((text) => text !== "");
+
+const partsByNumber = (names: string[], pattern: RegExp): Map<number, string> => {
+    const map = new Map<number, string>();
+    for (const name of names) {
+        const match = pattern.exec(name);
+        if (match !== null) {
+            map.set(Number(match[1]), name);
+        }
+    }
+    return map;
+};
+
+export const pptxDeriver: Deriver = {
+    name: "pptx",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const zip = unzipSync(new Uint8Array(await readFile(absPath)));
+        const names = Object.keys(zip);
+        const decoder = new TextDecoder();
+        const xmlOf = (name: string): string => decoder.decode(zip[name]);
+        const slides = partsByNumber(names, SLIDE_PART);
+        const notes = partsByNumber(names, NOTES_PART);
+        const sections: string[] = [];
+        for (const number of [...slides.keys()].toSorted((a, b) => a - b)) {
+            const lines = slideParagraphs(xmlOf(slides.get(number) ?? ""));
+            const section = [`## Slide ${number}`, ...lines];
+            const notesPart = notes.get(number);
+            if (notesPart !== undefined) {
+                const noteLines = slideParagraphs(xmlOf(notesPart)).filter((line) => !/^\d+$/.test(line)); // slide-number placeholder
+                if (noteLines.length > 0) {
+                    section.push("", "Notes:", ...noteLines.map((line) => `> ${line}`));
+                }
+            }
+            sections.push(section.join("\n"));
+        }
+        return {
+            markdown: sections.join("\n\n"),
+            notes: slides.size === 0 ? ["no slide parts found in this presentation"] : [],
+        };
+    },
+};

package/src/lib/derivers/profile.ts

@@ -0,0 +1,172 @@
+import { readFile } from "node:fs/promises";
+import { plural } from "@intentic/base/format";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+
+/* V8 profiles (node --cpu-prof, --heap-prof, DevTools): a sample tree whose reading is a ranked table, not the JSON. */
+
+const TOP_ROWS = 25;
+
+interface CallFrame {
+    readonly functionName?: string;
+    readonly url?: string;
+    readonly lineNumber?: number;
+}
+
+// --cpu-prof: a flat node list, each sample naming the node that was on top of the stack.
+interface CpuNode {
+    readonly id: number;
+    readonly callFrame: CallFrame;
+    readonly children?: readonly number[];
+}
+
+interface CpuProfile {
+    readonly nodes: readonly CpuNode[];
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly samples?: readonly number[];
+    readonly timeDeltas?: readonly number[];
+}
+
+// --heap-prof: a tree of allocation sites, each with the bytes sampled as allocated there.
+interface HeapNode {
+    readonly callFrame: CallFrame;
+    readonly selfSize: number;
+    readonly children?: readonly HeapNode[];
+}
+
+interface HeapProfile {
+    readonly head: HeapNode;
+}
+
+interface Row {
+    readonly key: string;
+    self: number;
+    total: number;
+}
+
+// One function across every node it appears at: V8 splits a function into a node per distinct caller path.
+const keyOf = (frame: CallFrame): string => {
+    const name = frame.functionName === undefined || frame.functionName === "" ? "(anonymous)" : frame.functionName;
+    if (frame.url === undefined || frame.url === "") {
+        return name;
+    }
+    // Line numbers are 0-based in the profile and 1-based everywhere a person or an editor reads them.
+    const file = frame.url.replace(/^file:\/\//u, "");
+    return `${name} ${file}:${String((frame.lineNumber ?? 0) + 1)}`;
+};
+
+const rowOf = (rows: Map<string, Row>, key: string): Row => {
+    const existing = rows.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const row: Row = { key, self: 0, total: 0 };
+    rows.set(key, row);
+    return row;
+};
+
+const percent = (part: number, whole: number): string => (whole === 0 ? "0.0%" : `${((part / whole) * 100).toFixed(1)}%`);
+
+const table = (heading: string, unit: (value: number) => string, rows: readonly Row[], whole: number): string =>
+    [
+        `## ${heading}`,
+        "",
+        "| self | self % | total | total % | function |",
+        "| ---: | ---: | ---: | ---: | --- |",
+        ...rows.map((row) => `| ${unit(row.self)} | ${percent(row.self, whole)} | ${unit(row.total)} | ${percent(row.total, whole)} | \`${row.key.replaceAll("|", "\\|")}\` |`),
+    ].join("\n");
+
+const ranked = (rows: Map<string, Row>, by: "self" | "total"): readonly Row[] => [...rows.values()].toSorted((left, right) => right[by] - left[by]).slice(0, TOP_ROWS);
+
+const milliseconds = (microseconds: number): string => `${(microseconds / 1_000).toFixed(1)} ms`;
+
+const kilobytes = (bytes: number): string => `${(bytes / 1_024).toFixed(1)} KB`;
+
+// Sample i's duration is the gap to the next sample; the last one takes the mean, since nothing follows it.
+const cpuDoc = (profile: CpuProfile): DerivedDoc => {
+    const samples = profile.samples ?? [];
+    const deltas = profile.timeDeltas ?? [];
+    const parent = new Map<number, number>();
+    const byId = new Map<number, CpuNode>();
+    for (const node of profile.nodes) {
+        byId.set(node.id, node);
+        for (const child of node.children ?? []) {
+            parent.set(child, node.id);
+        }
+    }
+    const span = profile.endTime - profile.startTime;
+    const meanGap = samples.length === 0 ? 0 : span / samples.length;
+    const rows = new Map<string, Row>();
+    for (const [index, id] of samples.entries()) {
+        const duration = deltas[index + 1] ?? meanGap;
+        const top = byId.get(id);
+        if (top === undefined) {
+            continue;
+        }
+        rowOf(rows, keyOf(top.callFrame)).self += duration;
+        // Inclusive time counts a function once per sample, however deep it recurses.
+        const onStack = new Set<string>();
+        for (let node: number | undefined = id; node !== undefined; node = parent.get(node)) {
+            const frame = byId.get(node)?.callFrame;
+            if (frame !== undefined && frame.functionName !== "(root)") {
+                onStack.add(keyOf(frame));
+            }
+        }
+        for (const key of onStack) {
+            rowOf(rows, key).total += duration;
+        }
+    }
+    const notes = samples.length === 0 ? ["no samples in this profile: it recorded nothing, or ran shorter than one sampling interval"] : [];
+    if (rows.size > TOP_ROWS) {
+        notes.push(`${plural(rows.size, "function")} sampled; each table shows the top ${String(TOP_ROWS)}`);
+    }
+    return {
+        title: `CPU profile: ${milliseconds(span)} over ${plural(samples.length, "sample")}`,
+        markdown: [table("By self time", milliseconds, ranked(rows, "self"), span), table("By total time", milliseconds, ranked(rows, "total"), span)].join("\n\n"),
+        notes,
+    };
+};
+
+const heapDoc = (profile: HeapProfile): DerivedDoc => {
+    const rows = new Map<string, Row>();
+    // Returns the subtree's bytes; a function's total counts each path through it once, recursion included.
+    const walk = (node: HeapNode, ancestors: ReadonlySet<string>): number => {
+        const key = keyOf(node.callFrame);
+        const isRoot = node.callFrame.functionName === "(root)";
+        const inside = isRoot || ancestors.has(key) ? ancestors : new Set([...ancestors, key]);
+        const below = (node.children ?? []).reduce((sum, child) => sum + walk(child, inside), 0);
+        if (!isRoot) {
+            const row = rowOf(rows, key);
+            row.self += node.selfSize;
+            if (!ancestors.has(key)) {
+                row.total += node.selfSize + below;
+            }
+        }
+        return node.selfSize + below;
+    };
+    const whole = walk(profile.head, new Set());
+    const notes = whole === 0 ? ["no allocations sampled in this profile"] : [];
+    if (rows.size > TOP_ROWS) {
+        notes.push(`${plural(rows.size, "allocation site")} sampled; each table shows the top ${String(TOP_ROWS)}`);
+    }
+    return {
+        title: `Heap profile: ${kilobytes(whole)} sampled as allocated`,
+        markdown: [table("By bytes allocated here", kilobytes, ranked(rows, "self"), whole), table("By bytes allocated here and below", kilobytes, ranked(rows, "total"), whole)].join("\n\n"),
+        notes,
+    };
+};
+
+export const profileDeriver: Deriver = {
+    name: "profile",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const profile = JSON.parse(await readFile(absPath, "utf8")) as Partial<CpuProfile & HeapProfile>;
+        if (Array.isArray(profile.nodes) && typeof profile.startTime === "number" && typeof profile.endTime === "number") {
+            return cpuDoc(profile as CpuProfile);
+        }
+        if (profile.head !== undefined) {
+            return heapDoc(profile as HeapProfile);
+        }
+        return { markdown: "", notes: ["not a V8 CPU or heap profile: neither `nodes` with start and end times, nor a `head` node"] };
+    },
+};