brane 0.0.2 → 0.3.0

package/dist/test/files-browse.test.js

@@ -0,0 +1,393 @@
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { brotliCompressSync, deflateRawSync, gzipSync } from "node:zlib";
+import { browseFold, parseOffsetParam, MAX_INLINE } from "../files/browse.js";
+import { ReachError, streamSource } from "../files/bytes.js";
+import { Readable } from "node:stream";
+import { HEX_PAGE_BYTES, hexDumpRows, hexRowColumns, looksBinary } from "../shared/hex-dump.js";
+import { archiveFormatFor, normalizeMemberName } from "../files/archive.js";
+function crc32(buf) {
+    let c = ~0;
+    for (const b of buf) {
+        c ^= b;
+        for (let k = 0; k < 8; k++)
+            c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
+    }
+    return ~c >>> 0;
+}
+function makeZip(entries, prefix = Buffer.alloc(0)) {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const e of entries) {
+        const raw = Buffer.isBuffer(e.data) ? e.data : Buffer.from(e.data ?? "");
+        const body = e.deflate ? deflateRawSync(raw) : raw;
+        const name = Buffer.from(e.name, "utf8");
+        const flags = (e.encrypted ? 1 : 0) | 0x800;
+        const method = e.deflate ? 8 : 0;
+        const crc = crc32(raw);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(flags, 6);
+        local.writeUInt16LE(method, 8);
+        local.writeUInt16LE(0, 10);
+        local.writeUInt16LE((46 << 9) | (1 << 5) | 1, 12); // 2026-01-01
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(raw.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        locals.push(local, name, body);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(e.mode !== undefined ? (3 << 8) | 20 : 20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(flags, 8);
+        central.writeUInt16LE(method, 10);
+        central.writeUInt16LE(0, 12);
+        central.writeUInt16LE((46 << 9) | (1 << 5) | 1, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(raw.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(((e.mode ?? 0) << 16) >>> 0, 38);
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, name);
+        offset += 30 + name.length + body.length;
+    }
+    const cd = Buffer.concat(centrals);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(entries.length, 8);
+    eocd.writeUInt16LE(entries.length, 10);
+    eocd.writeUInt32LE(cd.length, 12);
+    eocd.writeUInt32LE(offset, 16);
+    return Buffer.concat([prefix, ...locals, cd, eocd]);
+}
+function tarHeader(name, size, type, link = "") {
+    const h = Buffer.alloc(512);
+    h.write(name.slice(0, 100), 0, "utf8");
+    h.write("0000644\0", 100);
+    h.write("0000000\0", 108);
+    h.write("0000000\0", 116);
+    h.write(size.toString(8).padStart(11, "0") + "\0", 124);
+    h.write("15107000000\0", 136);
+    h.write("        ", 148);
+    h.write(type, 156);
+    h.write(link, 157);
+    h.write("ustar\0", 257);
+    h.write("00", 263);
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148);
+    return h;
+}
+function pad(buf) {
+    const rem = buf.length % 512;
+    return rem ? Buffer.concat([buf, Buffer.alloc(512 - rem)]) : buf;
+}
+function makeTar(entries) {
+    const parts = [];
+    for (const e of entries) {
+        if (e.paxPath) {
+            const rec = (len) => `${len} path=${e.paxPath}\n`;
+            let len = rec(0).length;
+            while (rec(len).length !== len)
+                len = rec(len).length;
+            const body = Buffer.from(rec(len));
+            parts.push(tarHeader("PaxHeader", body.length, "x"), pad(body));
+        }
+        const data = Buffer.isBuffer(e.data) ? e.data : Buffer.from(e.data ?? "");
+        parts.push(tarHeader(e.name, data.length, e.type ?? "0", e.link), pad(data));
+    }
+    parts.push(Buffer.alloc(1024));
+    return Buffer.concat(parts);
+}
+// ── Fixture fold ────────────────────────────────────────────────────────────
+let fold;
+const MIME = { ".png": "image/png", ".pdf": "application/pdf" };
+const browse = (rel, opts = {}) => browseFold(fold, rel, { mimeTypes: MIME, ...opts });
+function json(r) {
+    assert.ok("json" in r, "expected a JSON answer");
+    assert.equal(r.status, 200, JSON.stringify(r.json));
+    return r.json;
+}
+function asFile(r) {
+    const j = json(r);
+    assert.equal(j.type, "file");
+    return j;
+}
+function asDir(r) {
+    const j = json(r);
+    assert.equal(j.type, "directory");
+    return j;
+}
+async function rawBytes(r) {
+    assert.ok("raw" in r, "expected a raw answer");
+    const parts = [];
+    for await (const c of r.raw.stream)
+        parts.push(c);
+    return Buffer.concat(parts);
+}
+const ELF = Buffer.concat([Buffer.from([0x7f, 0x45, 0x4c, 0x46, 2, 1, 1, 0]), Buffer.alloc(40000, 0xab)]);
+before(() => {
+    fold = mkdtempSync(join(tmpdir(), "brane-files-"));
+    mkdirSync(join(fold, "dir"));
+    writeFileSync(join(fold, "dir", "hello.ts"), "export const x = 1;\n");
+    writeFileSync(join(fold, "prog.bin"), ELF);
+    // Bigger than the inline limit, and binary: paged, never "too large".
+    writeFileSync(join(fold, "huge.bin"), Buffer.concat([Buffer.from([0]), Buffer.alloc(MAX_INLINE + 10, 1)]));
+    writeFileSync(join(fold, "pkg.zip"), makeZip([
+        { name: "README.md", data: "# pkg\n" },
+        { name: "src/main.ts", data: "const y: number = 2;\n".repeat(50), deflate: true },
+        { name: "src/deep/", data: "" },
+        { name: "bin/tool", data: ELF, deflate: true },
+        { name: "link", data: "src/main.ts", mode: 0o120777 },
+    ]));
+    writeFileSync(join(fold, "evil.zip"), makeZip([
+        { name: "../escape.txt", data: "nope" },
+        { name: "/etc/passwd", data: "root:x:0:0\n" },
+        { name: "a\\..\\..\\b.txt", data: "nope" },
+        { name: "ok.txt", data: "fine" },
+        { name: "secret.txt", data: "xxxx", encrypted: true },
+    ]));
+    // 64 MB of zeros that deflate to ~64 KB: the listing is instant, and a
+    // read of the member produces one page, never the whole thing.
+    writeFileSync(join(fold, "bomb.zip"), makeZip([{ name: "zeros", data: Buffer.alloc(64 * 1024 * 1024), deflate: true }]));
+    // A self-extractor's stub before the zip proper: every offset is short.
+    writeFileSync(join(fold, "sfx.zip"), makeZip([{ name: "inside.txt", data: "found me" }], Buffer.alloc(1000, 0x90)));
+    writeFileSync(join(fold, "fake.zip"), "this is not a zip at all\n");
+    const tar = makeTar([
+        { name: "./", type: "5" },
+        { name: "top.txt", data: "top\n" },
+        { name: "._top.txt", data: "AppleDouble" },
+        { name: "nested/dir/", type: "5" },
+        { name: "nested/dir/n.py", data: "print('hi')\n" },
+        { name: "short", paxPath: `${"long-".repeat(30)}name.txt`, data: "long named\n" },
+        { name: "sym", type: "2", link: "top.txt" },
+        { name: "hard", type: "1", link: "top.txt" },
+        { name: "../../etc/evil", data: "nope" },
+    ]);
+    writeFileSync(join(fold, "t.tar"), tar);
+    writeFileSync(join(fold, "t.tar.gz"), gzipSync(tar));
+    writeFileSync(join(fold, "t.tar.br"), brotliCompressSync(tar));
+    writeFileSync(join(fold, "notes.md.gz"), gzipSync("# compressed\n"));
+    writeFileSync(join(fold, "code.ts.gz"), gzipSync("let z = 3;\n"));
+    writeFileSync(join(fold, "junk.tar"), "not a tarball, just text that is long enough ".repeat(20));
+});
+// ── Hex ─────────────────────────────────────────────────────────────────────
+describe("hex dump rules", () => {
+    it("calls a file binary on a NUL in its first 8000 bytes, as git does", () => {
+        assert.equal(looksBinary(Buffer.from("plain text\n")), false);
+        assert.equal(looksBinary(Buffer.from([0x41, 0x00, 0x42])), true);
+        const late = Buffer.alloc(9000, 0x41);
+        late[8500] = 0;
+        assert.equal(looksBinary(late), false);
+    });
+    it("lays rows out like xxd, numbered from the page's offset", () => {
+        const rows = hexDumpRows(Buffer.from("Hello, world!\n\x00\x01ABC"), 0x20);
+        assert.deepEqual(rows, [
+            "00000020  48 65 6c 6c 6f 2c 20 77  6f 72 6c 64 21 0a 00 01  Hello, world!...",
+            "00000030  41 42 43                                          ABC",
+        ]);
+    });
+    it("narrows to eight bytes a row for a phone, columns still aligned", () => {
+        const rows = hexDumpRows(Buffer.from("0123456789"), 0, 8);
+        assert.deepEqual(rows, [
+            "00000000  30 31 32 33 34 35 36 37  01234567",
+            "00000008  38 39                    89",
+        ]);
+        assert.equal(rows[0].length, hexRowColumns(8));
+        assert.equal(hexDumpRows(new Uint8Array(16))[0].length, hexRowColumns(16));
+    });
+});
+describe("/api/files: plain files", () => {
+    it("serves text as before", async () => {
+        const f = asFile(await browse("dir/hello.ts"));
+        assert.equal(f.content, "export const x = 1;\n");
+        assert.equal(f.binary, undefined);
+    });
+    it("serves a binary file as its first hex page instead of mangled UTF-8", async () => {
+        const f = asFile(await browse("prog.bin"));
+        assert.equal(f.binary, true);
+        assert.equal(f.content, "");
+        assert.ok(f.hex);
+        assert.equal(f.hex.offset, 0);
+        assert.equal(f.hex.eof, false);
+        const page = Buffer.from(f.hex.data, "base64");
+        assert.equal(page.length, HEX_PAGE_BYTES);
+        assert.deepEqual(page.subarray(0, 4), Buffer.from([0x7f, 0x45, 0x4c, 0x46]));
+    });
+    it("pages further in with offset=, and says when the last page is reached", async () => {
+        const f = asFile(await browse("prog.bin", { offset: 2 * HEX_PAGE_BYTES }));
+        assert.ok(f.hex);
+        assert.equal(f.hex.eof, true);
+        assert.equal(Buffer.from(f.hex.data, "base64").length, ELF.length - 2 * HEX_PAGE_BYTES);
+    });
+    it("pages a binary past the inline limit rather than calling it too large", async () => {
+        const f = asFile(await browse("huge.bin"));
+        assert.equal(f.truncated, undefined);
+        assert.ok(f.hex);
+    });
+    it("streams any file raw, text included, so Download works on large text", async () => {
+        const bytes = await rawBytes(await browse("dir/hello.ts", { raw: true }));
+        assert.equal(bytes.toString(), "export const x = 1;\n");
+    });
+    it("refuses paths that leave the fold", async () => {
+        const r = await browse("../outside");
+        assert.equal(r.status, 400);
+        assert.equal((await browse("/etc/passwd")).status, 400);
+    });
+    it("validates offset=", () => {
+        assert.equal(parseOffsetParam(null), null);
+        assert.equal(parseOffsetParam("4096"), 4096);
+        assert.equal(parseOffsetParam("-1"), undefined);
+        assert.equal(parseOffsetParam("1e3"), undefined);
+        assert.equal(parseOffsetParam("99999999999999999999"), undefined);
+    });
+});
+// ── Zip ─────────────────────────────────────────────────────────────────────
+describe("/api/files: zip archives", () => {
+    it("marks archives in a directory listing", async () => {
+        const d = asDir(await browse(""));
+        const byName = new Map(d.entries.map((e) => [e.name, e]));
+        assert.equal(byName.get("pkg.zip")?.archive, true);
+        assert.equal(byName.get("t.tar.gz")?.archive, true);
+        assert.equal(byName.get("notes.md.gz")?.archive, undefined, "a single compressed file opens as a file");
+        assert.equal(byName.get("prog.bin")?.archive, undefined);
+    });
+    it("lists a zip as a directory, folders first, with implied folders", async () => {
+        const d = asDir(await browse("pkg.zip"));
+        assert.deepEqual(d.entries.map((e) => [e.name, e.is_dir]), [
+            ["bin", true], ["src", true], ["link", false], ["README.md", false],
+        ]);
+        assert.deepEqual(d.archive, { root: "pkg.zip", format: "zip" });
+        const src = asDir(await browse("pkg.zip/src"));
+        assert.deepEqual(src.entries.map((e) => e.name), ["deep", "main.ts"]);
+        assert.equal(src.path, "pkg.zip/src");
+    });
+    it("opens a deflated member with highlighting chosen by its own name", async () => {
+        const f = asFile(await browse("pkg.zip/src/main.ts"));
+        assert.equal(f.content, "const y: number = 2;\n".repeat(50));
+        assert.equal(f.highlight?.lang, "typescript");
+        assert.equal(f.archive?.root, "pkg.zip");
+    });
+    it("opens a binary member in the hex view, and streams it raw", async () => {
+        const f = asFile(await browse("pkg.zip/bin/tool"));
+        assert.ok(f.hex);
+        assert.deepEqual(Buffer.from(f.hex.data, "base64").subarray(0, 4), ELF.subarray(0, 4));
+        const bytes = await rawBytes(await browse("pkg.zip/bin/tool", { raw: true }));
+        assert.deepEqual(bytes, ELF);
+    });
+    it("shows a symlink member's target without following it", async () => {
+        const f = asFile(await browse("pkg.zip/link"));
+        assert.equal(f.link, "src/main.ts");
+        assert.equal(f.content, "");
+    });
+    it("still downloads the archive itself with raw=", async () => {
+        const bytes = await rawBytes(await browse("pkg.zip", { raw: true }));
+        assert.equal(bytes.readUInt32LE(0), 0x04034b50);
+    });
+    it("hides names that can't be placed, and says how many", async () => {
+        const d = asDir(await browse("evil.zip"));
+        assert.deepEqual(d.entries.map((e) => e.name).sort(), ["etc", "ok.txt", "secret.txt"]);
+        assert.equal(d.archive?.skipped, 2);
+        assert.equal(asFile(await browse("evil.zip/etc/passwd")).content, "root:x:0:0\n");
+    });
+    it("explains an encrypted member instead of failing", async () => {
+        const f = asFile(await browse("evil.zip/secret.txt"));
+        assert.match(f.notice ?? "", /encrypted/);
+    });
+    it("decodes only one page of a decompression bomb", async () => {
+        const d = asDir(await browse("bomb.zip"));
+        assert.equal(d.entries[0].size, 64 * 1024 * 1024, "the claimed size is displayed");
+        const before = process.memoryUsage().arrayBuffers;
+        const f = asFile(await browse("bomb.zip/zeros"));
+        assert.ok(f.hex);
+        assert.equal(Buffer.from(f.hex.data, "base64").length, HEX_PAGE_BYTES);
+        assert.ok(process.memoryUsage().arrayBuffers - before < 32 * 1024 * 1024);
+    });
+    it("finds a zip behind a self-extractor stub", async () => {
+        assert.equal(asFile(await browse("sfx.zip/inside.txt")).content, "found me");
+    });
+    it("shows a file named .zip that isn't one as the file it is", async () => {
+        const f = asFile(await browse("fake.zip"));
+        assert.equal(f.content, "this is not a zip at all\n");
+        assert.equal((await browse("fake.zip/anything")).status, 404);
+    });
+    it("404s a member that isn't there, and a path through a non-archive", async () => {
+        assert.equal((await browse("pkg.zip/nope.txt")).status, 404);
+        assert.equal((await browse("dir/hello.ts/x")).status, 404);
+    });
+});
+// ── Tar ─────────────────────────────────────────────────────────────────────
+for (const name of ["t.tar", "t.tar.gz", "t.tar.br"]) {
+    describe(`/api/files: ${name}`, () => {
+        it("lists members, with pax long names, and unsafe names and dotfiles hidden", async () => {
+            const d = asDir(await browse(name));
+            assert.deepEqual(d.entries.map((e) => e.name), [
+                "nested", "hard", `${"long-".repeat(30)}name.txt`, "sym", "top.txt",
+            ]);
+            assert.equal(d.archive?.skipped, 1);
+            assert.equal(d.entries.find((e) => e.name === "sym")?.link, "top.txt");
+        });
+        it("reads members, including one past earlier data", async () => {
+            assert.equal(asFile(await browse(`${name}/top.txt`)).content, "top\n");
+            const py = asFile(await browse(`${name}/nested/dir/n.py`));
+            assert.equal(py.content, "print('hi')\n");
+            assert.equal(py.highlight?.lang, "python");
+            assert.equal(asFile(await browse(`${name}/${"long-".repeat(30)}name.txt`)).content, "long named\n");
+        });
+        it("opens a hard link as its target and shows a symlink's target", async () => {
+            assert.equal(asFile(await browse(`${name}/hard`)).content, "top\n");
+            assert.equal(asFile(await browse(`${name}/sym`)).link, "top.txt");
+        });
+    });
+}
+describe("/api/files: other compressed files", () => {
+    it("opens a .gz as what it compresses, named by what's inside", async () => {
+        const md = asFile(await browse("notes.md.gz"));
+        assert.equal(md.content, "# compressed\n");
+        assert.equal(md.path, "notes.md.gz");
+        const ts = asFile(await browse("code.ts.gz"));
+        assert.equal(ts.highlight?.lang, "typescript");
+    });
+    it("shows a .tar that isn't tar as the file it is", async () => {
+        const f = asFile(await browse("junk.tar"));
+        assert.match(f.content, /^not a tarball/);
+    });
+});
+describe("archive names and formats", () => {
+    it("recognizes zip-family and tar-family names", () => {
+        assert.equal(archiveFormatFor("a/b.jar")?.kind, "zip");
+        assert.equal(archiveFormatFor("report.DOCX")?.kind, "zip");
+        assert.equal(archiveFormatFor("x.tgz")?.kind, "tar");
+        assert.deepEqual(archiveFormatFor("log.txt.gz"), { kind: "single", label: "gz", codec: "gzip", inner: "log.txt" });
+        assert.equal(archiveFormatFor(".zip"), null, "a bare extension is a dotfile, not an archive");
+        assert.equal(archiveFormatFor("zipper.ts"), null);
+    });
+    it("normalizes member names, refusing any that climb", () => {
+        assert.equal(normalizeMemberName("/abs/x"), "abs/x");
+        assert.equal(normalizeMemberName("./a//b/./c"), "a/b/c");
+        assert.equal(normalizeMemberName("win\\style\\path"), "win/style/path");
+        assert.equal(normalizeMemberName("a/../b"), null);
+        assert.equal(normalizeMemberName("..\\x"), null);
+        assert.equal(normalizeMemberName("nul\0byte"), null);
+        assert.equal(normalizeMemberName("./"), "", "the root: nothing to place, nothing wrong");
+    });
+});
+describe("stream reach", () => {
+    it("refuses a read past the reach limit rather than decoding up to it", async () => {
+        let opened = 0;
+        const src = streamSource(() => { opened++; return Readable.from([Buffer.alloc(100)]); }, null, 0, 0, 50);
+        await assert.rejects(src.read(60, 10), ReachError);
+        assert.equal(opened, 0, "nothing was decoded");
+        assert.equal((await src.read(40, 100)).length, 10, "a read that straddles the limit is cut at it");
+    });
+});
+//# sourceMappingURL=files-browse.test.js.map

package/dist/test/files-find.test.js

@@ -0,0 +1,272 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { gzipSync } from "node:zlib";
+import { ReachError, fileSource, streamSource } from "../files/bytes.js";
+import { openFoldSource } from "../files/browse.js";
+import { FindSlots, MAX_NEEDLE_BYTES, parseByteQuery, parseFindQuery, scanSource, } from "../files/find.js";
+/** A body delivered in the given chunk sizes, the way a decompressor
+ *  delivers one: the scanner must not care where the seams fall. */
+function chunked(data, sizes, reach) {
+    const open = () => {
+        const parts = [];
+        let at = 0;
+        for (let i = 0; at < data.length; i++) {
+            const n = Math.max(1, sizes[i % sizes.length]);
+            parts.push(data.subarray(at, at + n));
+            at += n;
+        }
+        return Readable.from(parts);
+    };
+    return streamSource(open, data.length, 0, 0, reach);
+}
+async function scan(source, needles, from = 0, opts = {}) {
+    const events = [];
+    const done = await scanSource(source, needles, from, (e) => events.push(e), opts);
+    const hits = events.flatMap((e) => (e.type === "hits" ? e.hits : []));
+    return { hits, done, events };
+}
+/** What a scan must find: each needle's non-overlapping hits, merged by offset. */
+function reference(data, needles, from = 0) {
+    const lower = Buffer.from(data.map((b) => (b >= 0x41 && b <= 0x5a ? b | 0x20 : b)));
+    const out = [];
+    needles.forEach((needle, n) => {
+        const hay = needle.caseless ? lower : data;
+        let i = from;
+        while (true) {
+            const at = hay.indexOf(needle.bytes, i);
+            if (at < 0)
+                break;
+            out.push({ at, len: needle.bytes.length, n });
+            i = at + needle.bytes.length;
+        }
+    });
+    out.sort((a, b) => a.at - b.at || a.n - b.n);
+    return out.map((h) => [h.at, h.len]);
+}
+describe("parseByteQuery", () => {
+    it("reads lowercase text as caseless and mixed case as exact", () => {
+        assert.deepEqual(parseByteQuery("text").map((n) => [n.kind, n.bytes.toString(), n.caseless]), [["text", "text", true]]);
+        assert.deepEqual(parseByteQuery("TEXT").map((n) => [n.kind, n.bytes.toString(), n.caseless]), [["text", "TEXT", false]]);
+    });
+    it("reads a run of hex pairs as bytes too, with or without spaces or 0x", () => {
+        for (const q of ["cf fa ed fe", "cffaedfe", "0xCFFAEDFE", "CF FA ED FE"]) {
+            const hex = parseByteQuery(q).find((n) => n.kind === "hex");
+            assert.ok(hex, q);
+            assert.deepEqual([...hex.bytes], [0xcf, 0xfa, 0xed, 0xfe]);
+            assert.equal(hex.caseless, false);
+        }
+    });
+    it("keeps both readings of an ambiguous word", () => {
+        const needles = parseByteQuery("cafe");
+        assert.deepEqual(needles.map((n) => n.kind), ["text", "hex"]);
+        assert.deepEqual([...needles[1].bytes], [0xca, 0xfe]);
+    });
+    it("does not read an odd digit count or a non-hex word as hex", () => {
+        assert.deepEqual(parseByteQuery("abc").map((n) => n.kind), ["text"]);
+        assert.deepEqual(parseByteQuery("c0ffee!").map((n) => n.kind), ["text"]);
+        assert.deepEqual(parseByteQuery("a b").map((n) => n.kind), ["text"]);
+    });
+    it("does not trim: a lone space is a query", () => {
+        assert.deepEqual(parseByteQuery(" ").map((n) => [...n.bytes]), [[0x20]]);
+        assert.deepEqual(parseByteQuery(""), []);
+    });
+    it("lowercases ASCII only, so the bytes of `İ` stay put", () => {
+        const [text] = parseByteQuery("İx");
+        assert.equal(text.caseless, false); // `İ` is uppercase: exact
+        assert.deepEqual(text.bytes, Buffer.from("İx"));
+    });
+    it("refuses a needle past the cap", () => {
+        assert.ok("error" in parseFindQuery("x".repeat(MAX_NEEDLE_BYTES + 1)));
+        assert.ok(Array.isArray(parseFindQuery("x".repeat(MAX_NEEDLE_BYTES))));
+        assert.ok("error" in parseFindQuery(""));
+    });
+});
+describe("scanSource", () => {
+    it("finds what a naive search finds, wherever the chunk seams fall", async () => {
+        // A small alphabet makes needles recur, overlap each other, and straddle
+        // seams often; case varies so the fold is exercised too.
+        let seed = 7;
+        const rand = (n) => {
+            seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+            return seed % n;
+        };
+        const alphabet = Buffer.from("abAB\x00\xca\xfe");
+        for (let trial = 0; trial < 200; trial++) {
+            const data = Buffer.from(Array.from({ length: 50 + rand(400) }, () => alphabet[rand(alphabet.length)]));
+            const q = ["ab", "aba", "cafe", "b", "BA", "a\x00", "abab"][rand(7)];
+            const needles = parseByteQuery(q);
+            const sizes = Array.from({ length: 5 }, () => 1 + rand(9));
+            const from = rand(3) === 0 ? rand(data.length) : 0;
+            const { hits, done } = await scan(chunked(data, sizes), needles, from, { maxHits: 1e9, maxPages: 1e9 });
+            assert.deepEqual(hits, reference(data, needles, from), `trial ${trial}: ${JSON.stringify(q)} ${sizes}`);
+            assert.equal(done.stop, "eof");
+            assert.equal(done.next, null);
+            assert.equal(done.scanned, data.length);
+        }
+    });
+    it("reports hits in offset order even when a longer needle's hit completes a chunk later", async () => {
+        // `cafe` as text (4 bytes) starts at 2 and is whole only in the second
+        // chunk; the hex needle ca fe (2 bytes) at 6 is whole in the first. Order
+        // must still be 2 before 6.
+        const data = Buffer.concat([Buffer.from("xxca"), Buffer.from("fe"), Buffer.from([0xca, 0xfe]), Buffer.from("xx")]);
+        const { hits } = await scan(chunked(data, [3, 5]), parseByteQuery("cafe"));
+        assert.deepEqual(hits, [[2, 4], [6, 2]]);
+    });
+    it("stops at the page window and says where the next hit is", async () => {
+        // One hit per 16-byte page, pages 0..9.
+        const data = Buffer.alloc(160, 0x2e);
+        for (let p = 0; p < 10; p++)
+            data.write("Z", p * 16 + 3);
+        const needles = parseByteQuery("z");
+        const { hits, done } = await scan(chunked(data, [7]), needles, 0, { pageBytes: 16, maxPages: 4 });
+        assert.deepEqual(hits.map((h) => h[0]), [3, 19, 35, 51]);
+        assert.equal(done.stop, "pages");
+        assert.equal(done.next, 67);
+        // …and the next window picks up exactly there.
+        const again = await scan(chunked(data, [7]), needles, done.next, { pageBytes: 16, maxPages: 4 });
+        assert.deepEqual(again.hits.map((h) => h[0]), [67, 83, 99, 115]);
+    });
+    it("counts a hit that straddles a page boundary as both pages", async () => {
+        const data = Buffer.alloc(64, 0x2e);
+        data.write("xy", 15); // pages 0 and 1
+        data.write("xy", 40); // page 2
+        const { hits, done } = await scan(chunked(data, [64]), parseByteQuery("xy"), 0, { pageBytes: 16, maxPages: 2 });
+        assert.deepEqual(hits, [[15, 2]]);
+        assert.equal(done.stop, "pages");
+        assert.equal(done.next, 40);
+    });
+    it("stops at the hit cap: a one-byte query in a file made of that byte", async () => {
+        const data = Buffer.alloc(100_000);
+        const { hits, done } = await scan(chunked(data, [4096]), parseByteQuery("00"), 0, { maxHits: 50 });
+        assert.equal(hits.length, 50);
+        assert.equal(done.stop, "hits");
+        assert.equal(done.next, 50);
+        // It stopped in the first chunk, not after reading the file.
+        assert.ok(done.scanned <= 4096);
+    });
+    it("stops on its time budget with a place to resume", async () => {
+        let t = 0;
+        const data = Buffer.alloc(1000, 0x2e);
+        data.write("q", 900);
+        const { hits, done } = await scan(chunked(data, [100]), parseByteQuery("q"), 0, {
+            budgetMs: 250,
+            now: () => (t += 100),
+        });
+        assert.deepEqual(hits, []);
+        assert.equal(done.stop, "time");
+        assert.ok(done.next !== null && done.next < 900);
+        const rest = await scan(chunked(data, [100]), parseByteQuery("q"), done.next);
+        assert.deepEqual(rest.hits, [[900, 1]]);
+    });
+    it("stops at the reach limit in a compressed body, keeping what it found before it", async () => {
+        const data = Buffer.alloc(300, 0x2e);
+        data.write("hit", 10);
+        data.write("hit", 250);
+        const { hits, done } = await scan(chunked(data, [32], 200), parseByteQuery("hit"));
+        assert.deepEqual(hits, [[10, 3]]);
+        assert.equal(done.stop, "reach");
+        assert.equal(done.scanned, 200);
+    });
+    it("stops when cancelled", async () => {
+        const c = new AbortController();
+        c.abort();
+        const { done } = await scan(chunked(Buffer.alloc(100), [10]), parseByteQuery("00"), 0, { signal: c.signal });
+        assert.equal(done.stop, "cancelled");
+    });
+    it("resumes a cancelled scan without losing a hit it was holding at the seam", async () => {
+        // `NEEDLE` is split across the first seam. The scan is cancelled as the
+        // second chunk arrives, while `NEE` is still held back; resuming from the
+        // chunk's end would never see the hit.
+        const data = Buffer.from("........NEEDLE..........");
+        const c = new AbortController();
+        const src = streamSource(() => Readable.from((function* () {
+            yield data.subarray(0, 11);
+            c.abort();
+            yield data.subarray(11);
+        })()), data.length, 0);
+        const first = await scan(src, parseByteQuery("NEEDLE"), 0, { signal: c.signal });
+        assert.deepEqual(first.hits, []);
+        assert.equal(first.done.stop, "cancelled");
+        assert.ok(first.done.next !== null && first.done.next <= 8);
+        const rest = await scan(chunked(data, [5]), parseByteQuery("NEEDLE"), first.done.next);
+        assert.deepEqual(rest.hits, [[8, 6]]);
+    });
+    it("reads a file on disk from an offset", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "brane-find-"));
+        const p = join(dir, "blob.bin");
+        const data = Buffer.alloc(3 * 1024 * 1024 + 5);
+        data.write("NEEDLE", 1024 * 1024 - 3); // across the first 1 MB read
+        data.write("NEEDLE", 3 * 1024 * 1024 - 1);
+        writeFileSync(p, data);
+        const src = fileSource(p, data.length, 0);
+        const { hits, done } = await scan(src, parseByteQuery("NEEDLE"));
+        assert.deepEqual(hits, [[1024 * 1024 - 3, 6], [3 * 1024 * 1024 - 1, 6]]);
+        assert.equal(done.stop, "eof");
+        const later = await scan(src, parseByteQuery("NEEDLE"), 1024 * 1024);
+        assert.deepEqual(later.hits, [[3 * 1024 * 1024 - 1, 6]]);
+    });
+});
+describe("ByteSource.chunks", () => {
+    it("throws ReachError past the reach limit rather than ending quietly", async () => {
+        const src = chunked(Buffer.alloc(100), [30], 50);
+        let got = 0;
+        await assert.rejects(async () => {
+            for await (const c of src.chunks(0))
+                got += c.length;
+        }, ReachError);
+        assert.equal(got, 50);
+    });
+    it("ends normally when the body ends exactly at the limit", async () => {
+        const src = chunked(Buffer.alloc(50), [30], 50);
+        let got = 0;
+        for await (const c of src.chunks(10))
+            got += c.length;
+        assert.equal(got, 40);
+    });
+});
+describe("FindSlots", () => {
+    it("supersedes the oldest scan rather than refusing a new one", () => {
+        const slots = new FindSlots(2);
+        const a = slots.admit();
+        const b = slots.admit();
+        assert.equal(slots.size, 2);
+        const c = slots.admit();
+        assert.equal(a.signal.aborted, true);
+        assert.equal(b.signal.aborted, false);
+        assert.equal(c.signal.aborted, false);
+        assert.equal(slots.size, 2);
+        b.release();
+        c.release();
+        a.release(); // releasing a superseded scan is harmless
+        assert.equal(slots.size, 0);
+    });
+});
+describe("openFoldSource", () => {
+    const fold = mkdtempSync(join(tmpdir(), "brane-find-fold-"));
+    mkdirSync(join(fold, "sub"));
+    writeFileSync(join(fold, "sub", "a.bin"), Buffer.from("\x00\x01hello\x00"));
+    writeFileSync(join(fold, "notes.txt.gz"), gzipSync(Buffer.from("x".repeat(1000) + "buried")));
+    it("opens a plain file", async () => {
+        const src = await openFoldSource(fold, "sub/a.bin");
+        assert.ok(!("error" in src));
+        const { hits } = await scan(src, parseByteQuery("hello"));
+        assert.deepEqual(hits, [[2, 5]]);
+    });
+    it("searches a .gz as what it compresses, as the hex view shows it", async () => {
+        const src = await openFoldSource(fold, "notes.txt.gz");
+        assert.ok(!("error" in src));
+        const { hits } = await scan(src, parseByteQuery("buried"));
+        assert.deepEqual(hits, [[1000, 6]]);
+    });
+    it("refuses what isn't a file, or isn't in the fold", async () => {
+        assert.deepEqual(await openFoldSource(fold, "sub"), { status: 400, error: "Not a file" });
+        assert.equal((await openFoldSource(fold, "../etc/passwd")).status, 400);
+        assert.equal((await openFoldSource(fold, "/etc/passwd")).status, 400);
+        assert.equal((await openFoldSource(fold, "nope.bin")).status, 404);
+    });
+});
+//# sourceMappingURL=files-find.test.js.map