@intentic/fileq 1.317.0

package/src/lib/derivers/epub.ts

@@ -0,0 +1,130 @@
+import { readFile } from "node:fs/promises";
+import { posix } from "node:path";
+import { unzipSync, type Unzipped } from "fflate";
+import { bodyOf, metaOf, parseHtml } from "@intentic/webq/dom";
+import { renderMarkdown } from "@intentic/webq/markdown";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { attributeOf, decodeEntities } from "../xml.js";
+
+/* EPUBs: a zip of XHTML chapters, read in the order the package document (the OPF) says they are read. */
+
+const MAX_MARKDOWN_BYTES = 2 * 1024 * 1024;
+
+interface ManifestItem {
+    readonly href: string;
+    readonly mediaType: string;
+    readonly nav: boolean;
+}
+
+interface Package {
+    readonly dir: string;
+    readonly title: string | undefined;
+    readonly manifest: Map<string, ManifestItem>;
+    readonly spine: string[];
+}
+
+const decoder = new TextDecoder();
+
+const partOf = (zip: Unzipped, name: string): string | undefined => (zip[name] === undefined ? undefined : decoder.decode(zip[name]));
+
+const manifestOf = (opf: string): Map<string, ManifestItem> => {
+    const items = new Map<string, ManifestItem>();
+    for (const match of opf.matchAll(/<(?:opf:)?item\b([^>]*?)\/?>/g)) {
+        const attributes = match[1] ?? "";
+        const id = attributeOf(attributes, "id");
+        const href = attributeOf(attributes, "href");
+        if (id !== undefined && href !== undefined) {
+            items.set(id, {
+                href,
+                mediaType: attributeOf(attributes, "media-type") ?? "",
+                nav: (attributeOf(attributes, "properties") ?? "").split(/\s+/).includes("nav"),
+            });
+        }
+    }
+    return items;
+};
+
+const spineOf = (opf: string): string[] =>
+    [...opf.matchAll(/<(?:opf:)?itemref\b([^>]*?)\/?>/g)]
+        .map((match) => attributeOf(match[1] ?? "", "idref"))
+        .filter((idref): idref is string => idref !== undefined);
+
+// container.xml names the OPF; the OPF names everything else. Undefined when either is missing.
+const readPackage = (zip: Unzipped): Package | undefined => {
+    const container = partOf(zip, "META-INF/container.xml");
+    const opfPath = container === undefined ? undefined : /full-path\s*=\s*"([^"]+)"/.exec(container)?.[1];
+    const opf = opfPath === undefined ? undefined : partOf(zip, opfPath);
+    if (opfPath === undefined || opf === undefined) {
+        return undefined;
+    }
+    const titleMatch = /<dc:title[^>]*>([\s\S]*?)<\/dc:title>/.exec(opf);
+    const raw = titleMatch?.[1]?.trim() ?? "";
+    return { dir: posix.dirname(opfPath), title: raw === "" ? undefined : decodeEntities(raw), manifest: manifestOf(opf), spine: spineOf(opf) };
+};
+
+// One spine entry as a markdown section: undefined when it is not a chapter (the nav document, a stylesheet,
+// an empty page); "missing" when the package names a file the archive does not carry.
+const chapterOf = (zip: Unzipped, pkg: Package, idref: string): string | "missing" | undefined => {
+    const item = pkg.manifest.get(idref);
+    if (item === undefined || item.nav || !/x?html/.test(item.mediaType)) {
+        return undefined;
+    }
+    const path = posix.normalize(posix.join(pkg.dir, decodeURIComponent(item.href.split("#")[0] ?? item.href)));
+    const html = partOf(zip, path);
+    if (html === undefined) {
+        return "missing";
+    }
+    const doc = parseHtml(html);
+    const body = bodyOf(doc);
+    const markdown = body === undefined ? "" : renderMarkdown(body).trim();
+    if (markdown === "") {
+        return undefined;
+    }
+    return markdown.startsWith("#") ? markdown : `## ${metaOf(doc).title || posix.basename(path)}\n\n${markdown}`;
+};
+
+const notesOf = (rendered: number, chapters: number, missing: number, capped: boolean): string[] => {
+    const notes: string[] = [];
+    if (capped) {
+        notes.push(`showing ${rendered} of ${chapters} chapters: cut at ${Math.round(MAX_MARKDOWN_BYTES / 1024 / 1024)} MB of text`);
+    }
+    if (missing > 0) {
+        notes.push(`${missing} spine item${missing === 1 ? "" : "s"} named in the package but absent from the archive`);
+    }
+    if (chapters === 0) {
+        notes.push("no readable chapters in this EPUB");
+    }
+    return notes;
+};
+
+export const epubDeriver: Deriver = {
+    name: "epub",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const zip = unzipSync(new Uint8Array(await readFile(absPath)));
+        const pkg = readPackage(zip);
+        if (pkg === undefined) {
+            return { markdown: "", notes: ["no package document (OPF) found: META-INF/container.xml is missing or points nowhere"] };
+        }
+        const sections: string[] = [];
+        let bytes = 0;
+        let chapters = 0;
+        let missing = 0;
+        for (const idref of pkg.spine) {
+            const chapter = chapterOf(zip, pkg, idref);
+            if (chapter === undefined) {
+                continue;
+            }
+            if (chapter === "missing") {
+                missing += 1;
+                continue;
+            }
+            chapters += 1;
+            if (bytes < MAX_MARKDOWN_BYTES) {
+                sections.push(chapter); // past the cap a chapter is counted, not rendered, so the note can say how many
+                bytes += chapter.length;
+            }
+        }
+        return { markdown: sections.join("\n\n"), title: pkg.title, notes: notesOf(sections.length, chapters, missing, bytes >= MAX_MARKDOWN_BYTES) };
+    },
+};

package/src/lib/derivers/html.ts

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { bodyOf, metaOf, parseHtml } from "@intentic/webq/dom";
+import { renderMarkdown } from "@intentic/webq/markdown";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+
+/* Local HTML files, through webq's own writer — the same DOM → markdown conventions a fetched page gets, but with NO fit-pruning. */
+
+export const htmlDeriver: Deriver = {
+    name: "html",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const doc = parseHtml(await readFile(absPath, "utf8"));
+        const body = bodyOf(doc);
+        const meta = metaOf(doc);
+        return {
+            markdown: body === undefined ? "" : renderMarkdown(body),
+            title: meta.title === "" ? undefined : meta.title,
+            notes: [],
+        };
+    },
+};

package/src/lib/derivers/image.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import exifr from "exifr";
+import { imageSize } from "image-size";
+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).
+// 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;
+
+// Deterministic tier: dimensions, format, and EXIF facts left behind; no caption, since describing pixels needs a
+// vision model.
+// The sidecar says explicitly that no description was generated, so that reads as "not generated", not "nothing to
+// see".
+
+// EXIF fields worth a line each, in the order they help: what took it, when, where, how it's oriented.
+const EXIF_LINES: readonly { readonly label: string; readonly keys: readonly string[] }[] = [
+    { label: "Camera", keys: ["Make", "Model"] },
+    { label: "Taken", keys: ["DateTimeOriginal", "CreateDate"] },
+    { label: "Software", keys: ["Software"] },
+    { label: "Orientation", keys: ["Orientation"] },
+];
+
+export const imageDeriver: Deriver = {
+    name: "image",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const bytes = await readFile(absPath);
+        const lines: string[] = [];
+        try {
+            const dims = imageSize(bytes);
+            lines.push(`- Format: ${dims.type ?? "unknown"}`, `- Dimensions: ${dims.width}×${dims.height}`);
+        } catch {
+            lines.push("- Dimensions: unreadable");
+        }
+        const exif = (await parseExif(bytes).catch(() => undefined)) as Record<string, unknown> | undefined;
+        if (exif !== undefined) {
+            for (const { label, keys } of EXIF_LINES) {
+                const parts = keys.map((key) => exif[key]).filter((value) => value !== undefined && value !== "");
+                if (parts.length > 0) {
+                    lines.push(`- ${label}: ${parts.map((part) => (part instanceof Date ? part.toISOString() : String(part))).join(" ")}`);
+                }
+            }
+            if (typeof exif["latitude"] === "number" && typeof exif["longitude"] === "number") {
+                lines.push(`- GPS: ${exif["latitude"].toFixed(5)}, ${exif["longitude"].toFixed(5)}`);
+            }
+        }
+        return {
+            markdown: lines.join("\n"),
+            notes: ["no visual description: image captioning is a later, model-backed tier — vision models should Read the image itself"],
+        };
+    },
+};

package/src/lib/derivers/ipynb.ts

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import { plural } from "@intentic/base/format";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+
+/* Jupyter notebooks: JSON whose cells ARE the document. */
+
+const MAX_OUTPUT_LINES = 40;
+
+interface Output {
+    readonly output_type?: string;
+    readonly text?: string | string[];
+    readonly data?: Record<string, string | string[]>;
+    readonly ename?: string;
+    readonly evalue?: string;
+}
+
+interface Cell {
+    readonly cell_type?: string;
+    readonly source?: string | string[];
+    readonly outputs?: Output[];
+}
+
+interface Notebook {
+    readonly cells?: Cell[];
+    readonly metadata?: { readonly language_info?: { readonly name?: string }; readonly kernelspec?: { readonly language?: string } };
+}
+
+interface Counters {
+    rich: number;
+    clipped: number;
+}
+
+// nbformat stores multi-line text as an array of lines (newlines included) or, from older writers, one string.
+const joined = (value: string | string[] | undefined): string => (Array.isArray(value) ? value.join("") : (value ?? ""));
+
+const linesOf = (value: string | string[] | undefined): string[] => joined(value).trimEnd().split("\n");
+
+const outputLines = (output: Output, counters: Counters): string[] => {
+    if (output.output_type === "stream") {
+        return linesOf(output.text);
+    }
+    if (output.output_type === "error") {
+        return [`${output.ename ?? "Error"}: ${output.evalue ?? ""}`.trimEnd()];
+    }
+    if (output.data === undefined) {
+        return [];
+    }
+    const plain = output.data["text/plain"];
+    if (plain !== undefined) {
+        return linesOf(plain);
+    }
+    counters.rich += 1;
+    return [`[${Object.keys(output.data).join(", ")} output omitted]`];
+};
+
+const codeCell = (cell: Cell, source: string, language: string, counters: Counters): string => {
+    const block = [`\`\`\`${language}`, source, "```"];
+    const lines = (cell.outputs ?? []).flatMap((output) => outputLines(output, counters));
+    if (lines.length === 0) {
+        return block.join("\n");
+    }
+    const kept = lines.slice(0, MAX_OUTPUT_LINES);
+    if (lines.length > MAX_OUTPUT_LINES) {
+        counters.clipped += 1;
+        kept.push(`… ${lines.length - MAX_OUTPUT_LINES} more output lines`);
+    }
+    return [...block, "", "```text", ...kept, "```"].join("\n");
+};
+
+// One cell as a markdown section, or undefined for a cell with nothing to show.
+const sectionOf = (cell: Cell, language: string, counters: Counters): string | undefined => {
+    const source = joined(cell.source).trimEnd();
+    if (cell.cell_type === "code") {
+        return codeCell(cell, source, language, counters);
+    }
+    if (source === "") {
+        return undefined;
+    }
+    // Markdown cells are already markdown; raw cells are fenced so their text cannot pose as prose.
+    return cell.cell_type === "markdown" ? source : ["```text", source, "```"].join("\n");
+};
+
+const notesOf = (cellCount: number, counters: Counters): string[] => {
+    const notes: string[] = [];
+    if (cellCount === 0) {
+        notes.push("no cells in this notebook");
+    }
+    if (counters.clipped > 0) {
+        notes.push(`${plural(counters.clipped, "cell")}: output cut at ${MAX_OUTPUT_LINES} lines`);
+    }
+    if (counters.rich > 0) {
+        notes.push(`${plural(counters.rich, "rich output")} (images, HTML) omitted: a notebook's pictures need the notebook itself`);
+    }
+    return notes;
+};
+
+export const ipynbDeriver: Deriver = {
+    name: "ipynb",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const notebook = JSON.parse(await readFile(absPath, "utf8")) as Notebook;
+        const language = notebook.metadata?.language_info?.name ?? notebook.metadata?.kernelspec?.language ?? "python";
+        const cells = Array.isArray(notebook.cells) ? notebook.cells : [];
+        const counters: Counters = { rich: 0, clipped: 0 };
+        const sections = cells.map((cell) => sectionOf(cell, language, counters)).filter((section): section is string => section !== undefined);
+        // The first markdown heading is the notebook's own idea of its title.
+        const title = cells
+            .filter((cell) => cell.cell_type === "markdown")
+            .map((cell) => /^#\s+(.+)$/m.exec(joined(cell.source))?.[1]?.trim())
+            .find((heading) => heading !== undefined);
+        return { markdown: sections.join("\n\n"), title, notes: notesOf(cells.length, counters) };
+    },
+};

package/src/lib/derivers/load-cost.test.ts

@@ -0,0 +1,44 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// What a fileq run costs before it does anything. `derive.ts` imports all eleven derivers so `read` and `derive`
+// cannot disagree about a file, which means one deriver's top-level `import` is paid by every run of the CLI: an
+// agent reading a png, a sweep with nothing stale in it, `fileq --version`.
+// Measured when this guard was written, on the sandbox image: loading these three took ~1.3s of a ~1.4s no-op run,
+// and moving them inside `derive()` took `fileq --version` from ~560ms to ~120ms. A file of that format pays the
+// same load it always did, once, in the process that actually parses it.
+// Re-measure with: `node -e "import('exceljs')"` against the clock, and add anything else of that size here.
+const LOAD_LAZILY = ["exceljs", "mammoth", "music-metadata"];
+
+const HERE = import.meta.dirname;
+
+const deriverSources = async (): Promise<{ name: string; source: string }[]> => {
+    const names = (await readdir(HERE)).filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"));
+    return Promise.all(names.map(async (name) => ({ name, source: await readFile(join(HERE, name), "utf8") })));
+};
+
+describe("what a deriver costs to load", () => {
+    it("keeps the heavy parsers out of every run that does not use them", async () => {
+        const statik: string[] = [];
+        for (const { name, source } of await deriverSources()) {
+            for (const module of LOAD_LAZILY) {
+                // A value import: `import x from "exceljs"`. `import type` is erased by the compiler and costs nothing,
+                // and `await import("exceljs")` inside derive() is the whole point.
+                if (new RegExp(String.raw`^import (?!type )[^;]*from "${module}";`, "m").test(source)) {
+                    statik.push(`${name} → ${module}`);
+                }
+            }
+        }
+        expect(statik).toEqual([]);
+    });
+
+    // The same rule read from the other side: each of those parsers is still reachable, just later. A deriver that
+    // dropped its parser entirely would pass the test above by doing nothing at all.
+    it("still loads each of them where its own format is parsed", async () => {
+        const sources = await deriverSources();
+        for (const module of LOAD_LAZILY) {
+            const users = sources.filter(({ source }) => source.includes(`await import("${module}")`));
+            expect({ module, users: users.length }).toEqual({ module, users: 1 });
+        }
+    });
+});

package/src/lib/derivers/media.ts

@@ -0,0 +1,51 @@
+import type { DerivedDoc, Deriver } from "./deriver.js";
+
+/* Media derivation reads container duration, codecs, and tags without decoding frames. */
+
+// music-metadata is 0.2s to load, and only a recording needs it; see xlsx.ts for why that is loaded inside derive().
+
+const formatDuration = (seconds: number): string => {
+    const whole = Math.round(seconds);
+    const minutes = Math.floor(whole / 60);
+    return minutes === 0 ? `${whole}s` : `${minutes}m ${String(whole % 60).padStart(2, "0")}s`;
+};
+
+export const mediaDeriver: Deriver = {
+    name: "media",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const { parseFile } = await import("music-metadata");
+        const meta = await parseFile(absPath, { duration: true });
+        const lines: string[] = [];
+        const { format, common } = meta;
+        if (format.container !== undefined) {
+            lines.push(`- Container: ${format.container}${format.codec === undefined ? "" : ` (${format.codec})`}`);
+        }
+        if (format.duration !== undefined) {
+            lines.push(`- Duration: ${formatDuration(format.duration)}`);
+        }
+        if (format.sampleRate !== undefined) {
+            lines.push(`- Sample rate: ${format.sampleRate} Hz${format.numberOfChannels === undefined ? "" : `, ${format.numberOfChannels}ch`}`);
+        }
+        if (format.bitrate !== undefined) {
+            lines.push(`- Bitrate: ${Math.round(format.bitrate / 1000)} kbit/s`);
+        }
+        const tags: readonly (readonly [string, string | number | undefined])[] = [
+            ["Title", common.title],
+            ["Artist", common.artist],
+            ["Album", common.album],
+            ["Year", common.year],
+            ["Genre", common.genre?.join(", ")],
+        ];
+        for (const [label, value] of tags) {
+            if (value !== undefined && value !== "") {
+                lines.push(`- ${label}: ${value}`);
+            }
+        }
+        return {
+            markdown: lines.join("\n"),
+            title: common.title,
+            notes: ["no transcript: audio transcription is a later, whisper-backed tier"],
+        };
+    },
+};

package/src/lib/derivers/odp.ts

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { unzipSync } from "fflate";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { attributeOf, decodeEntities } from "../xml.js";
+
+/* OpenDocument presentations and drawings: one `## Slide N` section per page, the same shape pptx derives to. */
+
+const PAGE = /<draw:page\b([^>]*)>([\s\S]*?)<\/draw:page>/g;
+const NOTES = /<presentation:notes\b[^>]*>[\s\S]*?<\/presentation:notes>/g;
+const PARAGRAPH = /<text:(p|h)\b[^>]*(?:\/>|>([\s\S]*?)<\/text:\1>)/g;
+
+/** The text of one `<text:p>` or `<text:h>`, with the elements ODF uses for spacing turned back into spaces. */
+const lineOf = (inner: string): string =>
+    decodeEntities(
+        inner
+            .replaceAll(/<text:s\b[^>]*\/>/g, " ")
+            .replaceAll(/<text:tab\b[^>]*\/>/g, " ")
+            .replaceAll(/<text:line-break\b[^>]*\/>/g, " ")
+            .replaceAll(/<[^>]+>/g, ""),
+    )
+        .replaceAll(/\s+/g, " ")
+        .trim();
+
+const linesOf = (xml: string): string[] => [...xml.matchAll(PARAGRAPH)].map((match) => lineOf(match[2] ?? "")).filter((line) => line !== "");
+
+export const odpDeriver: Deriver = {
+    name: "odp",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const zip = unzipSync(new Uint8Array(await readFile(absPath)), { filter: (file) => file.name === "content.xml" });
+        const content = zip["content.xml"];
+        if (content === undefined) {
+            return { markdown: "", notes: ["no content.xml in this OpenDocument container"] };
+        }
+        const xml = new TextDecoder().decode(content);
+        const sections: string[] = [];
+        for (const page of xml.matchAll(PAGE)) {
+            const body = page[2] ?? "";
+            // The notes page travels inside the slide; it is what the speaker says, not what the slide shows.
+            const slide = body.replaceAll(NOTES, "");
+            const notes = (body.match(NOTES) ?? []).flatMap((part) => linesOf(part)).filter((line) => !/^\d+$/.test(line));
+            const name = attributeOf(page[1] ?? "", "draw:name");
+            const heading = `## Slide ${sections.length + 1}${name === undefined || name === "" ? "" : `: ${name}`}`;
+            const section = [heading, ...linesOf(slide)];
+            if (notes.length > 0) {
+                section.push("", "Notes:", ...notes.map((line) => `> ${line}`));
+            }
+            sections.push(section.join("\n"));
+        }
+        return { markdown: sections.join("\n\n"), notes: sections.length === 0 ? ["no slides in this presentation"] : [] };
+    },
+};

package/src/lib/derivers/ods.ts

@@ -0,0 +1,104 @@
+import { readFile } from "node:fs/promises";
+import { unzipSync } from "fflate";
+import type { DerivedDoc, Deriver } from "./deriver.js";
+import { attributeOf, decodeEntities } from "../xml.js";
+
+/* OpenDocument spreadsheets: one markdown table per sheet, the same shape xlsx derives to, so a reader cannot tell
+   which program wrote the file. */
+
+const MAX_ROWS_PER_SHEET = 200;
+const MAX_COLUMNS = 30;
+
+const TABLE = /<table:table\b([^>]*)>([\s\S]*?)<\/table:table>/g;
+const ROW = /<table:table-row\b([^>]*?)(?:\/>|>([\s\S]*?)<\/table:table-row>)/g;
+// The backreference keeps a covered cell's own closing tag straight; a merged-away cell is an empty one.
+const CELL = /<table:(covered-table-cell|table-cell)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/table:\1>)/g;
+
+const repeatOf = (attributes: string, name: string, limit: number): number => {
+    const value = Number.parseInt(attributeOf(attributes, name) ?? "1", 10);
+    return Number.isFinite(value) && value > 0 ? Math.min(value, limit) : 1;
+};
+
+/** A cell as a person reading the sheet would: its displayed text, or its value when it displays nothing. */
+const cellText = (attributes: string, inner: string): string => {
+    const shown = decodeEntities(
+        inner
+            .replaceAll(/<text:s\b[^>]*\/>/g, " ")
+            .replaceAll(/<text:tab\b[^>]*\/>/g, " ")
+            .replaceAll(/<\/text:p>/g, " ")
+            .replaceAll(/<[^>]+>/g, ""),
+    )
+        .replaceAll(/\s+/g, " ")
+        .trim();
+    return shown === "" ? (attributeOf(attributes, "office:value") ?? "") : shown;
+};
+
+const trimEnd = <T>(items: T[], empty: (item: T) => boolean): T[] => {
+    let end = items.length;
+    while (end > 0 && empty(items[end - 1] as T)) {
+        end -= 1;
+    }
+    return items.slice(0, end);
+};
+
+const cellsOf = (xml: string): string[] => {
+    const cells: string[] = [];
+    for (const cell of xml.matchAll(CELL)) {
+        const attributes = cell[2] ?? "";
+        const text = cell[1] === "covered-table-cell" ? "" : cellText(attributes, cell[3] ?? "");
+        for (let repeat = 0; repeat < repeatOf(attributes, "table:number-columns-repeated", MAX_COLUMNS); repeat += 1) {
+            cells.push(text);
+        }
+    }
+    return trimEnd(cells, (cell) => cell === "");
+};
+
+/** One `<table:table>`'s rows. Trailing empties are dropped: ODF pads every sheet out to its full width and height. */
+const rowsOf = (xml: string): string[][] => {
+    const rows: string[][] = [];
+    for (const row of xml.matchAll(ROW)) {
+        const cells = cellsOf(row[2] ?? "");
+        for (let repeat = 0; repeat < repeatOf(row[1] ?? "", "table:number-rows-repeated", MAX_ROWS_PER_SHEET); repeat += 1) {
+            rows.push(cells);
+        }
+    }
+    return trimEnd(rows, (row) => row.length === 0);
+};
+
+const tableRow = (cells: string[]): string => `| ${cells.map((cell) => cell.replaceAll("|", "\\|")).join(" | ")} |`;
+
+const sectionOf = (name: string, rows: string[][], notes: string[]): string => {
+    if (rows.length === 0) {
+        return `## ${name}\n\n(empty sheet)`;
+    }
+    const width = Math.min(MAX_COLUMNS, Math.max(...rows.map((row) => row.length)));
+    if (Math.max(...rows.map((row) => row.length)) > MAX_COLUMNS) {
+        notes.push(`sheet "${name}": showing ${MAX_COLUMNS} of ${Math.max(...rows.map((row) => row.length))} columns`);
+    }
+    if (rows.length > MAX_ROWS_PER_SHEET) {
+        notes.push(`sheet "${name}": showing ${MAX_ROWS_PER_SHEET} of ${rows.length} rows`);
+    }
+    const kept = rows.slice(0, MAX_ROWS_PER_SHEET).map((row) => Array.from({ length: width }, (_, index) => row[index] ?? ""));
+    const [header, ...body] = kept as [string[], ...string[][]];
+    return `## ${name}\n\n${[tableRow(header), tableRow(header.map(() => "---")), ...body.map(tableRow)].join("\n")}`;
+};
+
+export const odsDeriver: Deriver = {
+    name: "ods",
+    version: 1,
+    derive: async (absPath): Promise<DerivedDoc> => {
+        const zip = unzipSync(new Uint8Array(await readFile(absPath)), { filter: (file) => file.name === "content.xml" });
+        const content = zip["content.xml"];
+        if (content === undefined) {
+            return { markdown: "", notes: ["no content.xml in this OpenDocument container"] };
+        }
+        const xml = new TextDecoder().decode(content);
+        const notes: string[] = [];
+        const sections: string[] = [];
+        for (const table of xml.matchAll(TABLE)) {
+            const name = attributeOf(table[1] ?? "", "table:name") ?? `Sheet ${sections.length + 1}`;
+            sections.push(sectionOf(name, rowsOf(table[2] ?? ""), notes));
+        }
+        return { markdown: sections.join("\n\n"), notes: sections.length === 0 ? [...notes, "no sheets in this spreadsheet"] : notes };
+    },
+};