@intentic/fileq 1.318.0 → 1.320.0

package/src/app.ts

@@ -5,20 +5,19 @@ import { deriveCommand } from "./commands/derive.command.js";
 import { gitAttributesCommand } from "./commands/git-attributes.command.js";
 import { readCommand } from "./commands/read.command.js";
 import { renderCommand } from "./commands/render.command.js";
-import { sweepCommand } from "./commands/sweep.command.js";
 
 // The agent-facing contract, kept small — this is what `fileq --help` prints.
 const HELP = `fileq — binary workspace files as clean, budgeted markdown.
 
 Reads the formats an agent cannot: docx, xlsx, pptx, pdf (text layer), images
-(dimensions + EXIF), audio/video (duration + tags), html. Each workspace file
-gets a markdown SIDECAR under .intentic/local/cache/derived/<path>.md, kept
-fresh by content hash — reading a file twice derives once.
+(dimensions + EXIF), audio/video (duration + tags), html. Renderings are cached
+by content hash, so reading unchanged bytes again (the same file, a copy, a
+download outside the workspace) is instant; each workspace file also gets a
+markdown SIDECAR under .intentic/local/cache/derived/<path>.md.
 
   fileq <file>            print it as markdown (default: read), budgeted
   fileq read <file> --budget 8000
   fileq derive <file…>    converge named files' sidecars (stale→derive, gone→remove)
-  fileq sweep             converge the whole workspace, prune orphaned sidecars
   fileq read --plain <f>  the markdown alone, for a program; git's textconv driver
   fileq git-attributes    the gitattributes that route documents through it
 
@@ -47,7 +46,6 @@ export const app = buildApplication(
             check: checkCommand,
             render: renderCommand,
             derive: deriveCommand,
-            sweep: sweepCommand,
             gitAttributes: gitAttributesCommand,
         },
         defaultCommand: "read",

package/src/cli.integration.test.ts

@@ -1,8 +1,8 @@
-// CLI end-to-end against a temp workspace: derive, freshness, budgeted read, sweep with orphan pruning, the ignore
-// floor, and forged markers dying in the sidecar's bytes.
+// CLI end-to-end against a temp workspace: derive, freshness, the content cache, budgeted read, the ignore floor, and
+// forged markers dying in the sidecar's bytes.
 // Driven in-process through the same `run(app, …)` seam cli.ts calls (@intentic/agent-cli/testing); no build
 // artifact, no child process.
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { captureCli, type CliOutcome } from "@intentic/agent-cli/testing";
@@ -125,19 +125,16 @@ describe("read", () => {
         expect(out).toContain("Paragraph 199 with a good number");
     });
 
-    it("--plain on a file outside the workspace saves nothing, since git hands textconv one temp file per blob", async () => {
+    it("--plain on a file outside the workspace keeps its rendering by content, so git's next textconv of that blob is cached", async () => {
         const outside = mkdtempSync(join(tmpdir(), "fileq-outside-"));
-        const home = mkdtempSync(join(tmpdir(), "fileq-home-"));
-        process.env["FILEQ_HOME"] = home;
         try {
-            writeFileSync(join(outside, "memo.docx"), docxBytes("Memo", ["Kept in memory only."]));
+            writeFileSync(join(outside, "memo.docx"), docxBytes("Memo", ["A blob git handed over."]));
             const { out } = await fileq("read", "--plain", join(outside, "memo.docx"));
-            expect(out).toContain("Kept in memory only.");
-            expect(existsSync(join(home, "out"))).toBe(false);
+            expect(out).toContain("A blob git handed over.");
+            expect(out).not.toContain("saved:");
+            expect(JSON.parse((await fileq("read", "--json", join(outside, "memo.docx"))).out)).toMatchObject({ source: "fresh" });
         } finally {
-            delete process.env["FILEQ_HOME"];
             rmSync(outside, { recursive: true, force: true });
-            rmSync(home, { recursive: true, force: true });
         }
     });
 
@@ -164,26 +161,52 @@ describe("read", () => {
     });
 });
 
-describe("sweep", () => {
-    it("converges the tree, skips machine dirs, prunes orphans", async () => {
-        mkdirSync(join(root, "docs"), { recursive: true });
-        writeFileSync(join(root, "docs/photo.png"), pngBytes());
-        // An orphan: a shadow whose source never existed in this workspace.
-        mkdirSync(join(root, DERIVED_DIR, "gone"), { recursive: true });
-        writeFileSync(join(root, DERIVED_DIR, "gone/old.pdf.md"), "---\nsource: gone/old.pdf\n---\n");
-        const { out, exitCode } = await fileq("sweep");
-        expect(exitCode).toBe(0);
-        expect(out).toContain("derived docs/photo.png");
-        expect(out).toContain("pruned gone/old.pdf");
-        expect(out).not.toContain("node_modules");
-        expect(existsSync(sidecarOf("docs/photo.png"))).toBe(true);
-        expect(existsSync(join(root, DERIVED_DIR, "gone/old.pdf.md"))).toBe(false);
+describe("content cache", () => {
+    const readJson = async (path: string): Promise<{ source: string; path?: string }> => JSON.parse((await fileq("read", "--json", path)).out);
+
+    it("a copy of a workspace file at another path is fresh on its first read, with a sidecar of its own", async () => {
+        writeFileSync(join(root, "original.docx"), docxBytes("Original", ["Rendered once."]));
+        expect(await readJson(join(root, "original.docx"))).toMatchObject({ source: "derived" });
+        mkdirSync(join(root, "copies"), { recursive: true });
+        copyFileSync(join(root, "original.docx"), join(root, "copies/original.docx"));
+        expect(await readJson(join(root, "copies/original.docx"))).toMatchObject({ source: "fresh", path: sidecarOf("copies/original.docx") });
+        expect(readFileSync(sidecarOf("copies/original.docx"), "utf8")).toContain("source: copies/original.docx");
+    });
+
+    it("a file outside the workspace is derived once, then answered from the cache until its bytes change", async () => {
+        const outside = mkdtempSync(join(tmpdir(), "fileq-outside-"));
+        try {
+            writeFileSync(join(outside, "memo.docx"), docxBytes("Memo", ["First draft."]));
+            const first = await readJson(join(outside, "memo.docx"));
+            expect(first).toMatchObject({ source: "derived" });
+            expect(first.path?.startsWith(join(root, DERIVED_DIR, ".by-hash/"))).toBe(true);
+            expect(await readJson(join(outside, "memo.docx"))).toMatchObject({ source: "fresh", path: first.path });
+            writeFileSync(join(outside, "memo.docx"), docxBytes("Memo", ["Second draft."]));
+            const edited = await fileq("read", join(outside, "memo.docx"));
+            expect(edited.out).toContain("derived");
+            expect(edited.out).toContain("Second draft.");
+        } finally {
+            rmSync(outside, { recursive: true, force: true });
+        }
     });
 
-    it("--json answers counts a program can read", async () => {
-        const { out } = await fileq("sweep", "--json");
-        const summary = JSON.parse(out) as { derived: number; fresh: number };
-        expect(summary.fresh).toBeGreaterThan(0);
+    it("with no workspace and an unwritable cache, the rendering is still printed, and says nothing was saved", async () => {
+        const outside = mkdtempSync(join(tmpdir(), "fileq-outside-"));
+        delete process.env["WORKSPACE_ROOT"];
+        process.env["FILEQ_HOME"] = join(outside, "blocker");
+        try {
+            writeFileSync(join(outside, "blocker"), "a file where the cache directory would go");
+            writeFileSync(join(outside, "memo.docx"), docxBytes("Memo", ["Still readable."]));
+            const { out, exitCode } = await fileq("read", join(outside, "memo.docx"));
+            expect(exitCode).toBe(0);
+            expect(out).toContain("Still readable.");
+            expect(out).toContain("note: nothing saved: the rendering cache could not be written");
+            expect(out).not.toMatch(/^saved: /m);
+        } finally {
+            process.env["WORKSPACE_ROOT"] = root;
+            delete process.env["FILEQ_HOME"];
+            rmSync(outside, { recursive: true, force: true });
+        }
     });
 });
 

package/src/commands/check.command.ts

@@ -62,7 +62,7 @@ export const checkCommand = buildCommand({
     },
     async func(this: CommandContext, flags: CheckFlags, file: string) {
         const absPath = resolve(file);
-        // Loaded here, not at the top: every fileq run (a sweep, a read of a png) imports this module, and only a check
+        // Loaded here, not at the top: every fileq run (a derive, a read of a png) imports this module, and only a check
         // needs the checkers.
         const { CHECKABLE, checkFile } = await import("../lib/check/check.js");
         const outcome = await checkFile(absPath);

package/src/commands/derive.command.ts

@@ -37,7 +37,7 @@ export const deriveCommand = buildCommand({
             return;
         }
         if (files.length === 0) {
-            this.process.stdout.write("fileq: derive takes file paths (or run `fileq sweep` for the whole workspace)\n");
+            this.process.stdout.write("fileq: derive takes file paths\n");
             process.exitCode = 2;
             return;
         }

package/src/commands/read.command.ts

@@ -1,16 +1,11 @@
 /* `fileq read <file>` (also the default command): one file as markdown — a capsule line saying what happened, the content up to a token budget; `--plain` is the body alone, whole, for a program (git's textconv) rather than an agent. */
-import { createHash } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { toolOutDir } from "@intentic/agent-cli/env";
+import { basename, resolve } from "node:path";
 import { countParser } from "@intentic/agent-cli/flags";
 import { capsule, clip } from "@intentic/agent-cli/output";
 import { estimateTokens } from "@intentic/base/format";
 import { buildCommand, type CommandContext } from "@stricli/core";
-import { errorMessage } from "@intentic/base/errors";
-import { deriverStamp, neutralizeDoc, type DerivedDoc } from "../lib/derivers/deriver.js";
-import { detectFormat } from "../lib/formats.js";
-import { DERIVERS, ensureSidecar, type Outcome } from "../lib/derive.js";
+import { deriverStamp } from "../lib/derivers/deriver.js";
+import { DERIVERS, ensureSidecar, renderByContent, type Outcome } from "../lib/derive.js";
 import { workspaceRoot } from "../lib/env.js";
 
 interface ReadFlags {
@@ -25,7 +20,7 @@ export const readCommand = buildCommand({
         flags: {
             budget: { kind: "parsed", parse: countParser, default: "4000", brief: "Max stdout tokens; 0 prints only the capsule" },
             json: { kind: "boolean", default: false, brief: "Machine-readable result on stdout" },
-            plain: { kind: "boolean", default: false, brief: "The markdown alone, whole and unbudgeted; nothing saved for a file outside the workspace (git textconv)" },
+            plain: { kind: "boolean", default: false, brief: "The markdown alone, whole and unbudgeted (git textconv)" },
         },
         positional: {
             kind: "tuple",
@@ -35,8 +30,7 @@ export const readCommand = buildCommand({
     async func(this: CommandContext, flags: ReadFlags, file: string) {
         const absPath = resolve(file);
         const root = workspaceRoot();
-        const save = !flags.plain;
-        const result = root === undefined ? await readOutsideWorkspace(absPath, save) : await readInWorkspace(root, absPath, save);
+        const result = root === undefined ? await readOutsideWorkspace(undefined, absPath) : await readInWorkspace(root, absPath);
         if (result === undefined) {
             process.exitCode = 1;
             return;
@@ -52,11 +46,15 @@ export const readCommand = buildCommand({
             return;
         }
         const fields = [result.title ?? basename(absPath), result.format, `${result.tokens} tokens`, result.source];
-        this.process.stdout.write(capsule("fileq", fields, result.notes));
-        this.process.stdout.write(`saved: ${result.savedPath}\n`);
+        const notes = result.savedPath === undefined ? [...result.notes, "nothing saved: the rendering cache could not be written"] : result.notes;
+        this.process.stdout.write(capsule("fileq", fields, notes));
+        if (result.savedPath !== undefined) {
+            this.process.stdout.write(`saved: ${result.savedPath}\n`);
+        }
         if (flags.budget > 0 && result.body !== "") {
+            const whole = result.savedPath ?? `the output of \`fileq read --plain ${absPath}\``;
             this.process.stdout.write("---\n");
-            this.process.stdout.write(withFinalNewline(clip(result.body, flags.budget, result.savedPath, "document")));
+            this.process.stdout.write(withFinalNewline(clip(result.body, flags.budget, whole, "document")));
         }
     },
 });
@@ -67,16 +65,17 @@ interface ReadResult {
     readonly deriver: string;
     readonly body: string;
     readonly tokens: number;
-    readonly savedPath: string;
+    /** The file holding the whole rendering; undefined when the cache could not be written. */
+    readonly savedPath: string | undefined;
     readonly source: "derived" | "fresh";
     readonly title?: string | undefined;
     readonly notes: string[];
 }
 
-const readInWorkspace = async (root: string, absPath: string, save: boolean): Promise<ReadResult | undefined> => {
+const readInWorkspace = async (root: string, absPath: string): Promise<ReadResult | undefined> => {
     const outcome = await ensureSidecar(root, absPath);
     if (outcome.kind === "skipped" && outcome.reason === "outside-workspace") {
-        return readOutsideWorkspace(absPath, save);
+        return readOutsideWorkspace(root, absPath);
     }
     return fromOutcome(outcome);
 };
@@ -113,44 +112,23 @@ const fromOutcome = (outcome: Outcome): ReadResult | undefined => {
     }
 };
 
-/* Outside a workspace there is no sidecar tree; derive in memory and save the whole thing under the XDG, unless the
-   caller wants only the text (`--plain`: git hands textconv a temp file per blob, and a saved copy of each would pile up). */
-const readOutsideWorkspace = async (absPath: string, save: boolean): Promise<ReadResult | undefined> => {
-    const format = await detectFormat(absPath).catch(() => undefined);
-    if (format === undefined) {
-        process.stdout.write(`fileq: cannot read ${absPath}: unsupported or missing\n`);
-        return undefined;
-    }
-    // The same outcome a corrupt file gets inside a workspace (ensureSidecar's loud skip): a notebook that is
-    // not JSON, a docx that is not a zip, answers with the reason and exit 1, never a stack trace.
-    let doc: DerivedDoc;
-    try {
-        doc = neutralizeDoc(await DERIVERS[format].derive(absPath));
-    } catch (error) {
-        process.stdout.write(`fileq: cannot read ${absPath}: derive-failed (${format}): ${errorMessage(error).split("\n")[0]}\n`);
+// A file outside the workspace has no sidecar: the content cache alone keeps its rendering, and its entry is what `saved:`
+// names, so git's textconv reading the same blob twice derives it once.
+const readOutsideWorkspace = async (root: string | undefined, absPath: string): Promise<ReadResult | undefined> => {
+    const outcome = await renderByContent(root, absPath);
+    if (outcome.kind === "failed") {
+        process.stdout.write(`fileq: cannot read ${absPath}: ${outcome.reason}\n`);
         return undefined;
     }
-    const outDir = toolOutDir("fileq");
-    const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 8);
-    const savedPath = join(
-        outDir,
-        `${basename(absPath)
-            .toLowerCase()
-            .replaceAll(/[^a-z0-9.]+/g, "-")}-${hash}.md`,
-    );
-    if (save) {
-        await mkdir(outDir, { recursive: true });
-        await writeFile(savedPath, `${doc.markdown}\n`);
-    }
     return {
-        format,
-        deriver: deriverStamp(DERIVERS[format]),
-        body: doc.markdown,
-        tokens: estimateTokens(doc.markdown),
-        savedPath,
-        source: "derived",
-        title: doc.title,
-        notes: doc.notes,
+        format: outcome.format,
+        deriver: deriverStamp(DERIVERS[outcome.format]),
+        body: outcome.doc.markdown,
+        tokens: estimateTokens(outcome.doc.markdown),
+        savedPath: outcome.cachedPath,
+        source: outcome.kind,
+        title: outcome.doc.title,
+        notes: outcome.doc.notes,
     };
 };
 

package/src/lib/archives.ts

@@ -198,7 +198,7 @@ export const parseTarListing = (stdout: string): ArchiveEntry[] => {
     return entries;
 };
 
-// Long enough for a large archive's index, short enough that a hung tar cannot hold the sweep behind it.
+// Long enough for a large archive's index, short enough that a hung tar cannot hold a read hostage.
 const TAR_TIMEOUT_MS = 60_000;
 const TAR_MAX_BUFFER = 16 * 1024 * 1024;
 

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

@@ -73,10 +73,12 @@ const headingLevels = (styles: XmlElement | undefined): ReadonlyMap<string, numb
         const basedOn = childNamed(style, "w:basedOn")?.attrs["w:val"];
         return basedOn === undefined ? undefined : levelOf(basedOn, depth + 1);
     };
-    return new Map([...byId.keys()].flatMap((id) => {
-        const level = levelOf(id, 0);
-        return level === undefined ? [] : [[id, level] as const];
-    }));
+    return new Map(
+        [...byId.keys()].flatMap((id) => {
+            const level = levelOf(id, 0);
+            return level === undefined ? [] : [[id, level] as const];
+        }),
+    );
 };
 
 const headingOf = (paragraph: XmlElement, levels: ReadonlyMap<string, number>): number | undefined => {
@@ -106,7 +108,12 @@ const locate = (paragraphs: readonly XmlElement[], levels: ReadonlyMap<string, n
         const text = paragraphText(paragraph);
         const heading = headingOf(paragraph, levels);
         const number = index + 1;
-        const label = text.trim() !== "" ? `paragraph ${number} · ${excerpt(text, 40)}` : lastHeading === undefined ? `paragraph ${number}` : `paragraph ${number} · under ${lastHeading}`;
+        const label =
+            text.trim() !== ""
+                ? `paragraph ${number} · ${excerpt(text, 40)}`
+                : lastHeading === undefined
+                  ? `paragraph ${number}`
+                  : `paragraph ${number} · under ${lastHeading}`;
         located.push({ paragraph, number, text, heading });
         whereOf.set(paragraph, label);
         if (heading !== undefined && text.trim() !== "") {
@@ -151,7 +158,12 @@ const stepField = (node: XmlElement, open: OpenField[], fields: Field[], where:
         current.separated = true;
     } else if (type === "end") {
         open.pop();
-        fields.push({ instruction: current.instruction.trim(), result: current.result, hasResult: current.separated && current.result.trim() !== "", where: current.where });
+        fields.push({
+            instruction: current.instruction.trim(),
+            result: current.result,
+            hasResult: current.separated && current.result.trim() !== "",
+            where: current.where,
+        });
     }
 };
 
@@ -195,19 +207,33 @@ const bookmarkArgument = (instruction: string): string | undefined => {
 const fieldFindings = (fields: readonly Field[], bookmarks: ReadonlySet<string>, updatesOnOpen: boolean): Finding[] =>
     fields.flatMap((field): Finding[] => {
         const keyword = (field.instruction.split(/\s+/)[0] ?? "").toUpperCase();
-        if (field.result.trim().startsWith('Error!')) {
-            return [error("field-error", field.where, `the ${keyword} field shows ${excerpt(field.result)}: fix what it points at, then update fields`)];
+        if (field.result.trim().startsWith("Error!")) {
+            return [
+                error("field-error", field.where, `the ${keyword} field shows ${excerpt(field.result)}: fix what it points at, then update fields`),
+            ];
         }
         const bookmark = bookmarkArgument(field.instruction);
         if (bookmark !== undefined && !bookmarks.has(bookmark) && !BUILT_IN_ANCHORS.has(bookmark)) {
-            return [error("broken-reference", field.where, `the ${keyword} field points to bookmark "${bookmark}", which is not in the document: Word shows "Error! Reference source not found."`)];
+            return [
+                error(
+                    "broken-reference",
+                    field.where,
+                    `the ${keyword} field points to bookmark "${bookmark}", which is not in the document: Word shows "Error! Reference source not found."`,
+                ),
+            ];
         }
         if (keyword === "MERGEFIELD") {
-            return [warning("merge-field", field.where, `a mail-merge field is left in (${field.instruction}): it prints its placeholder, not a value`)];
+            return [
+                warning("merge-field", field.where, `a mail-merge field is left in (${field.instruction}): it prints its placeholder, not a value`),
+            ];
         }
         if (keyword === "TOC" && !field.hasResult) {
-            const when = updatesOnOpen ? "Word offers to update fields when the file opens" : "nothing fills it until someone updates fields (F9 in Word)";
-            return [warning("empty-toc", field.where, `the table of contents has no entries saved: ${when}, and previews and LibreOffice show it empty`)];
+            const when = updatesOnOpen
+                ? "Word offers to update fields when the file opens"
+                : "nothing fills it until someone updates fields (F9 in Word)";
+            return [
+                warning("empty-toc", field.where, `the table of contents has no entries saved: ${when}, and previews and LibreOffice show it empty`),
+            ];
         }
         if (!field.hasResult && keyword !== "" && !COMPUTED_FIELDS.has(keyword) && keyword !== "TOC") {
             return [warning("empty-field", field.where, `the ${keyword} field has no saved result, so it shows blank until fields are updated`)];
@@ -217,7 +243,13 @@ const fieldFindings = (fields: readonly Field[], bookmarks: ReadonlySet<string>,
 
 // --- references and images -------------------------------------------------------------------------------------
 
-const referenceFindings = (context: DocContext, part: string, tree: XmlElement, whereOfNode: (node: XmlElement) => string, referenced: Set<string>): Finding[] => {
+const referenceFindings = (
+    context: DocContext,
+    part: string,
+    tree: XmlElement,
+    whereOfNode: (node: XmlElement) => string,
+    referenced: Set<string>,
+): Finding[] => {
     const rels = context.pkg.rels(part);
     const findings: Finding[] = [];
     for (const node of everyElement(tree)) {
@@ -244,10 +276,20 @@ const referenceFinding = (
 ): Finding | undefined => {
     const isImage = node.name === "a:blip" || node.name === "v:imagedata";
     if (relationship === undefined) {
-        return error(isImage ? "missing-image" : "missing-part", where, `${isImage ? "an image" : node.name} refers to ${id}, which the document does not define: it shows as missing`);
+        return error(
+            isImage ? "missing-image" : "missing-part",
+            where,
+            `${isImage ? "an image" : node.name} refers to ${id}, which the document does not define: it shows as missing`,
+        );
     }
     if (relationship.external) {
-        return isImage ? warning("linked-image", where, `an image is linked from outside the file (${relationship.target}), so it will not show on anyone else's machine; embed it`) : undefined;
+        return isImage
+            ? warning(
+                  "linked-image",
+                  where,
+                  `an image is linked from outside the file (${relationship.target}), so it will not show on anyone else's machine; embed it`,
+              )
+            : undefined;
     }
     if (pkg.has(relationship.target)) {
         return undefined;
@@ -290,7 +332,13 @@ const wideImageFindings = (context: DocContext, body: XmlElement, owner: Readonl
             return [];
         }
         const where = paragraph === undefined ? "" : (context.whereOf.get(paragraph) ?? "");
-        return [warning("wide-image", where, `a picture is ${inches(cx)} wide in a ${inches(width)} text column, so it runs into the margin or is cut off; scale it to fit`)];
+        return [
+            warning(
+                "wide-image",
+                where,
+                `a picture is ${inches(cx)} wide in a ${inches(width)} text column, so it runs into the margin or is cut off; scale it to fit`,
+            ),
+        ];
     });
 };
 
@@ -298,11 +346,17 @@ const wideImageFindings = (context: DocContext, body: XmlElement, owner: Readonl
 
 const draftFindings = (context: DocContext, body: XmlElement): Finding[] => {
     const findings: Finding[] = [];
-    const changes = everyElement(body).filter((node) => ["w:ins", "w:del", "w:moveFrom", "w:moveTo"].includes(node.name) && node.children.some(isElement)).length;
+    const changes = everyElement(body).filter(
+        (node) => ["w:ins", "w:del", "w:moveFrom", "w:moveTo"].includes(node.name) && node.children.some(isElement),
+    ).length;
     if (changes > 0) {
-        findings.push(warning("tracked-changes", "", `${plural(changes, "tracked change")} still in the document: accept or reject them before it goes out`));
+        findings.push(
+            warning("tracked-changes", "", `${plural(changes, "tracked change")} still in the document: accept or reject them before it goes out`),
+        );
     }
-    const commentsPart = [...context.pkg.rels(context.main).values()].find((relationship) => relationship.kind === "comments" && !relationship.external);
+    const commentsPart = [...context.pkg.rels(context.main).values()].find(
+        (relationship) => relationship.kind === "comments" && !relationship.external,
+    );
     const comments = commentsPart === undefined ? undefined : context.pkg.xml(commentsPart.target);
     const count = comments === undefined ? 0 : childrenNamed(comments, "w:comment").length;
     if (count > 0) {
@@ -321,7 +375,13 @@ const paragraphFindings = (context: DocContext): Finding[] => {
         const hasPicture = descendantsNamed(located.paragraph, "w:drawing").length > 0 || descendantsNamed(located.paragraph, "w:pict").length > 0;
         if (located.heading !== undefined && located.text.trim() === "" && !hasPicture) {
             const level = located.heading === 0 ? "title" : `heading ${located.heading}`;
-            findings.push(warning("empty-heading", where, `empty ${level}: a blank line in the text and an empty entry in the navigation pane and any table of contents; delete it`));
+            findings.push(
+                warning(
+                    "empty-heading",
+                    where,
+                    `empty ${level}: a blank line in the text and an empty entry in the navigation pane and any table of contents; delete it`,
+                ),
+            );
         }
         if (TYPED_BULLET.test(located.text) && childAt(located.paragraph, "w:pPr", "w:numPr") === undefined) {
             typedBullets += 1;
@@ -330,7 +390,11 @@ const paragraphFindings = (context: DocContext): Finding[] => {
     }
     if (firstBullet !== undefined) {
         findings.push(
-            warning("typed-bullets", firstBullet, `${plural(typedBullets, "paragraph")} ${typedBullets === 1 ? "starts" : "start"} with a typed bullet character instead of a list style, so the list will not indent or renumber; use a list style`),
+            warning(
+                "typed-bullets",
+                firstBullet,
+                `${plural(typedBullets, "paragraph")} ${typedBullets === 1 ? "starts" : "start"} with a typed bullet character instead of a list style, so the list will not indent or renumber; use a list style`,
+            ),
         );
     }
     return findings;
@@ -343,7 +407,11 @@ const controlFindings = (body: XmlElement, whereOfNode: (node: XmlElement) => st
             const prompt = textIn(childNamed(control, "w:sdtContent") ?? control, "w:t");
             // A block-level control holds whole paragraphs; it is found by the first of them.
             const where = whereOfNode(descendantsNamed(control, "w:p")[0] ?? control);
-            return error("placeholder-control", where, `a content control still shows its prompt ${excerpt(prompt)}: enter the value or remove the control`);
+            return error(
+                "placeholder-control",
+                where,
+                `a content control still shows its prompt ${excerpt(prompt)}: enter the value or remove the control`,
+            );
         });
 
 const linkFindings = (body: XmlElement, bookmarks: ReadonlySet<string>, whereOfNode: (node: XmlElement) => string): Finding[] =>
@@ -352,7 +420,13 @@ const linkFindings = (body: XmlElement, bookmarks: ReadonlySet<string>, whereOfN
         if (anchor === undefined || bookmarks.has(anchor) || BUILT_IN_ANCHORS.has(anchor)) {
             return [];
         }
-        return [error("broken-link", whereOfNode(link), `the link ${excerpt(textIn(link, "w:t"))} points to bookmark "${anchor}", which is not in the document, so clicking it goes nowhere`)];
+        return [
+            error(
+                "broken-link",
+                whereOfNode(link),
+                `the link ${excerpt(textIn(link, "w:t"))} points to bookmark "${anchor}", which is not in the document, so clicking it goes nowhere`,
+            ),
+        ];
     });
 
 // Headers, footers and notes: each part's own images and relationships, located by the part's name.
@@ -360,7 +434,10 @@ const storyFindings = (context: DocContext, stories: readonly { part: string; tr
     stories.flatMap((story) => {
         const label = story.part.replace(/^word\//, "").replace(/\.xml$/, "");
         const referenced = new Set<string>();
-        return [...referenceFindings(context, story.part, story.tree, () => label, referenced), ...missingTargetFindings(context.pkg, story.part, label, referenced)];
+        return [
+            ...referenceFindings(context, story.part, story.tree, () => label, referenced),
+            ...missingTargetFindings(context.pkg, story.part, label, referenced),
+        ];
     });
 
 const openDocx = (bytes: Uint8Array): OoxmlPackage | CheckReport => {
@@ -368,7 +445,11 @@ const openDocx = (bytes: Uint8Array): OoxmlPackage | CheckReport => {
         return openPackage(bytes);
     } catch (cause) {
         if (cause instanceof NotAPackage) {
-            return { format: "docx", findings: [error("unreadable", "", `${cause.message}: this is not a Word file (or it is password-protected)`)], notes: [] };
+            return {
+                format: "docx",
+                findings: [error("unreadable", "", `${cause.message}: this is not a Word file (or it is password-protected)`)],
+                notes: [],
+            };
         }
         throw cause;
     }
@@ -403,7 +484,9 @@ export const checkDocx = (bytes: Uint8Array): CheckReport => {
             return tree === undefined ? [] : [{ part: relationship.target, tree }];
         });
     const bookmarks = new Set(
-        [body, ...stories.map((story) => story.tree)].flatMap((tree) => descendantsNamed(tree, "w:bookmarkStart").flatMap((mark) => mark.attrs["w:name"] ?? [])),
+        [body, ...stories.map((story) => story.tree)].flatMap((tree) =>
+            descendantsNamed(tree, "w:bookmarkStart").flatMap((mark) => mark.attrs["w:name"] ?? []),
+        ),
     );
     const context: DocContext = { pkg, main, paragraphs: located, whereOf, bookmarks };
     if (located.every((item) => item.text.trim() === "") && descendantsNamed(body, "w:drawing").length === 0) {
@@ -424,7 +507,9 @@ export const checkDocx = (bytes: Uint8Array): CheckReport => {
     );
     // A field showing "Error!" or a control showing its prompt is already named for what it is; the same words read as
     // leftover text would say it twice.
-    const explained = new Set(findings.filter((finding) => finding.rule === "field-error" || finding.rule === "placeholder-control").map((finding) => finding.where));
+    const explained = new Set(
+        findings.filter((finding) => finding.rule === "field-error" || finding.rule === "placeholder-control").map((finding) => finding.where),
+    );
     return {
         format: "docx",
         extent: plural(located.length, "paragraph"),

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

@@ -157,7 +157,13 @@ const linkFindings = async (pdf: PdfDocument, page: PdfPage, number: number): Pr
         // allow(silent-catch): pdf.js throws where the file's destination tree is damaged, and then the link goes nowhere too.
         const target = await pdf.getDestination(named).catch(() => null);
         if (target === null) {
-            findings.push(error("broken-link", `page ${number}`, `a link goes to "${named}", a destination the file does not define, so clicking it does nothing`));
+            findings.push(
+                error(
+                    "broken-link",
+                    `page ${number}`,
+                    `a link goes to "${named}", a destination the file does not define, so clicking it does nothing`,
+                ),
+            );
         }
     }
     return findings;
@@ -173,7 +179,10 @@ const openPdf = async (bytes: Uint8Array): Promise<PdfDocument | CheckReport> =>
         // Errors only: pdf.js otherwise narrates its recovery of a damaged file on the console, into the report.
         return await getDocumentProxy(bytes, { verbosity: 0 });
     } catch (cause) {
-        const reason = cause instanceof Error && cause.name === "PasswordException" ? "it is password-protected, so nothing past the password can be checked" : `it is not a readable PDF (${cause instanceof Error ? cause.message : String(cause)})`;
+        const reason =
+            cause instanceof Error && cause.name === "PasswordException"
+                ? "it is password-protected, so nothing past the password can be checked"
+                : `it is not a readable PDF (${cause instanceof Error ? cause.message : String(cause)})`;
         return { format: "pdf", findings: [error("unreadable", "", reason)], notes: [] };
     }
 };
@@ -211,14 +220,24 @@ export const checkPdf = async (bytes: Uint8Array): Promise<CheckReport> => {
     }
     for (const [font, pages] of unembedded) {
         findings.push(
-            warning("font-not-embedded", `page ${pageList(pages)}`, `text is set in ${font}, which the file does not carry: a reader without that font substitutes another, and lines can break differently; embed it`),
+            warning(
+                "font-not-embedded",
+                `page ${pageList(pages)}`,
+                `text is set in ${font}, which the file does not carry: a reader without that font substitutes another, and lines can break differently; embed it`,
+            ),
         );
     }
     if (sizes.size > 1) {
         const [common] = [...sizes.entries()].toSorted((a, b) => b[1].length - a[1].length);
         const odd = [...sizes.entries()].filter(([label]) => label !== common?.[0]);
         for (const [label, pages] of odd) {
-            findings.push(warning("page-size", `page ${pageList(pages)}`, `${plural(pages.length, "page is", "pages are")} ${label}, the rest ${common?.[0] ?? "another size"}`));
+            findings.push(
+                warning(
+                    "page-size",
+                    `page ${pageList(pages)}`,
+                    `${plural(pages.length, "page is", "pages are")} ${label}, the rest ${common?.[0] ?? "another size"}`,
+                ),
+            );
         }
     }
     if (characters === 0 && total > 0) {